Allow users to ignore optimization changes
[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 .. ghc-flag:: -fignore-optim-changes
546     :shortdesc: Do not recompile modules just to match changes to
547     optimisation flags. This is especially useful for avoiding
548     recompilation when using GHCi, and is enabled by default for
549     GHCi.
550     :type: dynamic
551     :reverse: -fno-ignore-optim-changes
552     :category: recompilation
553
554 .. ghc-flag:: -fignore-hpc-changes
555     :shortdesc: Do not recompile modules just to match changes to
556     HPC flags. This is especially useful for avoiding recompilation
557     when using GHCi, and is enabled by default for GHCi.
558     :type: dynamic
559     :reverse: -fno-ignore-hpc-changes
560     :category: recompilation
561
562 In the olden days, GHC compared the newly-generated ``.hi`` file with
563 the previous version; if they were identical, it left the old one alone
564 and didn't change its modification date. In consequence, importers of a
565 module with an unchanged output ``.hi`` file were not recompiled.
566
567 This doesn't work any more. Suppose module ``C`` imports module ``B``,
568 and ``B`` imports module ``A``. So changes to module ``A`` might require
569 module ``C`` to be recompiled, and hence when ``A.hi`` changes we should
570 check whether ``C`` should be recompiled. However, the dependencies of
571 ``C`` will only list ``B.hi``, not ``A.hi``, and some changes to ``A``
572 (changing the definition of a function that appears in an inlining of a
573 function exported by ``B``, say) may conceivably not change ``B.hi`` one
574 jot. So now…
575
576 GHC calculates a fingerprint (in fact an MD5 hash) of each interface
577 file, and of each declaration within the interface file. It also keeps
578 in every interface file a list of the fingerprints of everything it used
579 when it last compiled the file. If the source file's modification date
580 is earlier than the ``.o`` file's date (i.e. the source hasn't changed
581 since the file was last compiled), and the recompilation checking is on,
582 GHC will be clever. It compares the fingerprints on the things it needs
583 this time with the fingerprints on the things it needed last time
584 (gleaned from the interface file of the module being compiled); if they
585 are all the same it stops compiling early in the process saying
586 “Compilation IS NOT required”. What a beautiful sight!
587
588 You can read about `how all this
589 works <http://ghc.haskell.org/trac/ghc/wiki/Commentary/Compiler/RecompilationAvoidance>`__
590 in the GHC commentary.
591
592 .. _mutual-recursion:
593
594 How to compile mutually recursive modules
595 -----------------------------------------
596
597 .. index::
598    single: module system, recursion
599    single: recursion, between modules
600
601 GHC supports the compilation of mutually recursive modules. This section
602 explains how.
603
604 Every cycle in the module import graph must be broken by a ``hs-boot``
605 file. Suppose that modules ``A.hs`` and ``B.hs`` are Haskell source
606 files, thus: ::
607
608     module A where
609         import B( TB(..) )
610
611         newtype TA = MkTA Int
612
613         f :: TB -> TA
614         f (MkTB x) = MkTA x
615
616     module B where
617         import {-# SOURCE #-} A( TA(..) )
618
619         data TB = MkTB !Int
620
621         g :: TA -> TB
622         g (MkTA x) = MkTB x
623
624 .. index::
625    single: ``hs-boot`` files
626    single: importing, ``hi-boot`` files
627
628 Here ``A`` imports ``B``, but ``B`` imports ``A`` with a
629 ``{-# SOURCE #-}`` pragma, which breaks the circular dependency. Every
630 loop in the module import graph must be broken by a ``{-# SOURCE #-}``
631 import; or, equivalently, the module import graph must be acyclic if
632 ``{-# SOURCE #-}`` imports are ignored.
633
634 For every module ``A.hs`` that is ``{-# SOURCE #-}``-imported in this
635 way there must exist a source file ``A.hs-boot``. This file contains an
636 abbreviated version of ``A.hs``, thus: ::
637
638     module A where
639         newtype TA = MkTA Int
640
641 To compile these three files, issue the following commands:
642
643 .. code-block:: none
644
645       ghc -c A.hs-boot    -- Produces A.hi-boot, A.o-boot
646       ghc -c B.hs         -- Consumes A.hi-boot, produces B.hi, B.o
647       ghc -c A.hs         -- Consumes B.hi, produces A.hi, A.o
648       ghc -o foo A.o B.o  -- Linking the program
649
650 There are several points to note here:
651
652 -  The file ``A.hs-boot`` is a programmer-written source file. It must
653    live in the same directory as its parent source file ``A.hs``.
654    Currently, if you use a literate source file ``A.lhs`` you must also
655    use a literate boot file, ``A.lhs-boot``; and vice versa.
656
657 -  A ``hs-boot`` file is compiled by GHC, just like a ``hs`` file:
658
659    .. code-block:: none
660
661          ghc -c A.hs-boot
662
663    When a hs-boot file ``A.hs-boot`` is compiled, it is checked for
664    scope and type errors. When its parent module ``A.hs`` is compiled,
665    the two are compared, and an error is reported if the two are
666    inconsistent.
667
668 -  Just as compiling ``A.hs`` produces an interface file ``A.hi``, and
669    an object file ``A.o``, so compiling ``A.hs-boot`` produces an
670    interface file ``A.hi-boot``, and a pseudo-object file ``A.o-boot``:
671
672    -  The pseudo-object file ``A.o-boot`` is empty (don't link it!), but
673       it is very useful when using a Makefile, to record when the
674       ``A.hi-boot`` was last brought up to date (see :ref:`using-make`).
675
676    -  The ``hi-boot`` generated by compiling a ``hs-boot`` file is in
677       the same machine-generated binary format as any other
678       GHC-generated interface file (e.g. ``B.hi``). You can display its
679       contents with ``ghc --show-iface``. If you specify a directory for
680       interface files, the ``-ohidir`` flag, then that affects ``hi-boot`` files
681       too.
682
683 -  If hs-boot files are considered distinct from their parent source
684    files, and if a ``{-# SOURCE #-}`` import is considered to refer to
685    the hs-boot file, then the module import graph must have no cycles.
686    The command ``ghc -M`` will report an error if a cycle is found.
687
688 -  A module ``M`` that is ``{-# SOURCE #-}``\-imported in a program will
689    usually also be ordinarily imported elsewhere. If not, ``ghc --make``
690    automatically adds ``M`` to the set of modules it tries to compile
691    and link, to ensure that ``M``\'s implementation is included in the
692    final program.
693
694 A hs-boot file need only contain the bare minimum of information needed
695 to get the bootstrapping process started. For example, it doesn't need
696 to contain declarations for *everything* that module ``A`` exports, only
697 the things required by the module(s) that import ``A`` recursively.
698
699 A hs-boot file is written in a subset of Haskell:
700
701 -  The module header (including the export list), and import statements,
702    are exactly as in Haskell, and so are the scoping rules. Hence, to
703    mention a non-Prelude type or class, you must import it.
704
705 -  There must be no value declarations, but there can be type signatures
706    for values. For example: ::
707
708         double :: Int -> Int
709
710 -  Fixity declarations are exactly as in Haskell.
711
712 -  Vanilla type synonym declarations are exactly as in Haskell.
713
714 -  Open type and data family declarations are exactly as in Haskell.
715
716 -  A closed type family may optionally omit its equations, as in the
717    following example: ::
718
719         type family ClosedFam a where ..
720
721    The ``..`` is meant literally -- you should write two dots in your
722    file. Note that the ``where`` clause is still necessary to
723    distinguish closed families from open ones. If you give any equations
724    of a closed family, you must give all of them, in the same order as
725    they appear in the accompanying Haskell file.
726
727 -  A data type declaration can either be given in full, exactly as in
728    Haskell, or it can be given abstractly, by omitting the '=' sign and
729    everything that follows. For example: ::
730
731         data T a b
732
733    In a *source* program this would declare TA to have no constructors
734    (a GHC extension: see :ref:`nullary-types`), but in an hi-boot file
735    it means "I don't know or care what the constructors are". This is
736    the most common form of data type declaration, because it's easy to
737    get right. You *can* also write out the constructors but, if you do
738    so, you must write it out precisely as in its real definition.
739
740    If you do not write out the constructors, you may need to give a kind
741    annotation (:ref:`kinding`), to tell GHC the kind of the type
742    variable, if it is not "\*". (In source files, this is worked out
743    from the way the type variable is used in the constructors.) For
744    example: ::
745
746         data R (x :: * -> *) y
747
748    You cannot use ``deriving`` on a data type declaration; write an
749    ``instance`` declaration instead.
750
751 -  Class declarations is exactly as in Haskell, except that you may not
752    put default method declarations. You can also omit all the
753    superclasses and class methods entirely; but you must either omit
754    them all or put them all in.
755
756 -  You can include instance declarations just as in Haskell; but omit
757    the "where" part.
758
759 -  The default role for abstract datatype parameters is now
760    representational. (An abstract datatype is one with no constructors
761    listed.) To get another role, use a role annotation. (See
762    :ref:`roles`.)
763
764 .. _module-signatures:
765
766 Module signatures
767 -----------------
768
769 .. index::
770      single: signature files; Backpack; hsig files
771
772 GHC 8.2 supports module signatures (``hsig`` files), which allow you to
773 write a signature in place of a module implementation, deferring the
774 choice of implementation until a later point in time.  This feature is
775 not intended to be used without `Cabal
776 <http://www.haskell.org/cabal/>`__; this manual entry will focus
777 on the syntax and semantics of signatures.
778
779 To start with an example, suppose you had a module ``A`` which made use of some
780 string operations.  Using normal module imports, you would only
781 be able to pick a particular implementation of strings::
782
783     module Str where
784         type Str = String
785
786         empty :: Str
787         empty = ""
788
789         toString :: Str -> String
790         toString s = s
791
792     module A where
793         import Text
794         z = toString empty
795
796 By replacing ``Str.hs`` with a signature ``Str.hsig``, ``A`` (and
797 any other modules in this package) are now parametrized by
798 a string implementation::
799
800     signature Str where
801         data Str
802         empty :: Str
803         toString :: Str -> String
804
805 We can typecheck ``A`` against this signature, or we can instantiate
806 ``Str`` with a module that provides the following declarations.  Refer
807 to Cabal's documentation for a more in-depth discussion on how to
808 instantiate signatures.
809
810 Module signatures actually consist of two closely related features:
811
812 - The ability to define an ``hsig`` file, containing type definitions
813   and type signature for values which can be used by modules that
814   import the signature, and must be provided by the eventual
815   implementing module, and
816
817 - The ability to *inherit* required signatures from packages we
818   depend upon, combining the signatures into a single merged
819   signature which reflects the requirements of any locally defined
820   signature, as well as the requirements of our dependencies.
821
822 A signature file is denoted by an ``hsig`` file; every required
823 signature must have an ``hsig`` file (even if it is an empty one),
824 including required signatures inherited from dependencies.  Signatures
825 can be imported using an ordinary ``import Sig`` declaration.
826
827 ``hsig`` files are written in a variant of Haskell similar
828 to ``hs-boot`` files, but with some slight changes:
829
830 - The header of a signature is ``signature A where ...`` (instead
831   of the usual ``module A where ...``).
832
833 - Import statements and scoping rules are exactly as in Haskell.
834   To mention a non-Prelude type or class, you must import it.
835
836 - Unlike regular modules, the defined entities of
837   a signature include not only those written in the local
838   ``hsig`` file, but also those from inherited signatures
839   (as inferred from the :ghc-flag:`-package-id ⟨unit-id⟩` flags).
840   These entities are not considered in scope when typechecking
841   the local ``hsig`` file, but are available for import by
842   any module or signature which imports the signature.  The
843   one exception to this rule is the export list, described
844   below.
845
846   If a declaration occurs in multiple inherited signatures,
847   they will be *merged* together.  For values, we require
848   that the types from both signatures match exactly; however,
849   other declarations may merge in more interesting ways.
850   The merging operation in these cases has the effect of
851   textually replacing all occurrences of the old name with
852   a reference to the new, merged declaration.  For example,
853   if we have the following two signatures::
854
855     signature A where
856         data T
857         f :: T -> T
858
859     signature A where
860         data T = MkT
861         g :: T
862
863   the resulting merged signature would be::
864
865     signature A where
866         data T = MkT
867         f :: T -> T
868         g :: T
869
870 - If no export list is provided for a signature, the exports of
871   a signature are all of its defined entities merged with the
872   exports of all inherited signatures.
873
874   If you want to reexport an entity from a signature, you must
875   also include a ``module SigName`` export, so that all of the
876   entities defined in the signature are exported.  For example,
877   the following module exports both ``f`` and ``Int`` from
878   ``Prelude``::
879
880     signature A(module A, Int) where
881         import Prelude (Int)
882         f :: Int
883
884   Reexports merge with local declarations; thus, the signature above
885   would successfully merge with::
886
887     signature A where
888         data Int
889
890   The only permissible implementation of such a signature is a module
891   which reexports precisely the same entity::
892
893     module A (f, Int) where
894         import Prelude (Int)
895         f = 2 :: Int
896
897   Conversely, any entity requested by a signature can be provided
898   by a reexport from the implementing module.  This is different from
899   ``hs-boot`` files, which require every entity to be defined
900   locally in the implementing module.
901
902 - GHC has experimental support for *signature thinning*, which is used
903   when a signature has an explicit export list without a module export of the
904   signature itself.  In this case, the export list applies to the final export
905   list *after* merging, in particular, you may refer to entities which are not
906   declared in the body of the local ``hsig`` file.
907
908   The semantics in this case is that the set of required entities is defined
909   exclusively by its exports; if an entity is not mentioned in the export list,
910   it is not required.  The motivation behind this feature is to allow a library
911   author to provide an omnibus signature containing the type of every function
912   someone might want to use, while a client thins down the exports to the ones
913   they actually require.  For example, supposing that you have inherited a
914   signature for strings, you might write a local signature of this form, listing
915   only the entities that you need::
916
917     signature Str (Str, empty, append, concat) where
918         -- empty
919
920   A few caveats apply here.  First, it is illegal to export an entity
921   which refers to a locally defined type which itself is not exported
922   (GHC will report an error in this case).  Second, signatures which
923   come from dependencies which expose modules cannot be thinned in this
924   way (after all, the dependency itself may need the entity); these
925   requirements are unconditionally exported.  Finally, any module
926   reexports must refer to modules imported by the local signature
927   (even if an inherited signature exported the module).
928
929   We may change the syntax and semantics of this feature in the future.
930
931 - The declarations and types from signatures of dependencies
932   that will be merged in are not in scope when type checking
933   an ``hsig`` file.  To refer to any such type, you must
934   declare it yourself::
935
936     -- OK, assuming we inherited an A that defines T
937     signature A (T) where
938         -- empty
939
940     -- Not OK
941     signature A (T, f) where
942         f :: T -> T
943
944     -- OK
945     signature A (T, f) where
946         data T
947         f :: T -> T
948
949 - There must be no value declarations, but there can be type signatures
950   for values.  For example, we might define the signature::
951
952         signature A where
953             double :: Int -> Int
954
955   A module implementing ``A`` would have to export the function
956   ``double`` with a type definitionally equal to the signature.
957   Note that this means you can't implement ``double`` using
958   a polymorphic function ``double :: Num a => a -> a``.
959
960   Note that signature matching does check if *fixity* matches, so be
961   sure specify fixity of ordinary identifiers if you intend to use them
962   with backticks.
963
964 - Fixity, type synonym, open type/data family declarations
965   are permitted as in normal Haskell.
966
967 - Closed type family declarations are permitted as in normal
968   Haskell.  They can also be given abstractly, as in the
969   following example::
970
971     type family ClosedFam a where ..
972
973   The ``..`` is meant literally -- you should write two dots in
974   your file.  The ``where`` clause distinguishes closed families
975   from open ones.
976
977 - A data type declaration can either be given in full, exactly
978   as in Haskell, or it can be given abstractly, by omitting the '='
979   sign and everything that follows.  For example: ::
980
981         signature A where
982             data T a b
983
984   Abstract data types can be implemented not only with data
985   declarations, but also newtypes and type synonyms (with the
986   restriction that a type synonym must be fully eta-reduced,
987   e.g., ``type T = ...`` to be accepted.)  For example,
988   the following are all valid implementations of the T above::
989
990         -- Algebraic data type
991         data T a b = MkT a b
992
993         -- Newtype
994         newtype T a b = MkT (a, b)
995
996         -- Type synonym
997         data T2 a b = MkT2 a a b b
998         type T = T2
999
1000   Data type declarations merge only with other data type
1001   declarations which match exactly, except abstract data,
1002   which can merge with ``data``, ``newtype`` or ``type``
1003   declarations.  Merges with type synonyms are especially useful:
1004   suppose you are using a package of strings which has left the type of
1005   characters in the string unspecified::
1006
1007         signature Str where
1008             data Str
1009             data Elem
1010             head :: Str -> Elem
1011
1012   If you locally define a signature which specifies
1013   ``type Elem = Char``, you can now use ``head`` from the
1014   inherited signature as if it returned a ``Char``.
1015
1016   If you do not write out the constructors, you may need to give a kind to tell
1017   GHC what the kinds of the type variables are, if they are not the default
1018   ``*``.  Unlike regular data type declarations, the return kind of an
1019   abstract data declaration can be anything (in which case it probably
1020   will be implemented using a type synonym.)  This can be used
1021   to allow compile-time representation polymorphism (as opposed to
1022   `run-time representation polymorphism <#runtime-rep>`__),
1023   as in this example::
1024
1025         signature Number where
1026             import GHC.Types
1027             data Rep :: RuntimeRep
1028             data Number :: TYPE Rep
1029             plus :: Number -> Number -> Number
1030
1031   Roles of type parameters are subject to the subtyping
1032   relation ``phantom < representational < nominal``: for example,
1033   an abstract type with a nominal type parameter can be implemented
1034   using a concrete type with a representational type parameter.
1035   Merging respects this subtyping relation (e.g., ``nominal``
1036   merged with ``representational`` is ``representational``.)
1037   Roles in signatures default to ``nominal``, which gives maximum
1038   flexibility on the implementor's side.  You should only need to
1039   give an explicit role annotation if a client of the signature
1040   would like to coerce the abstract type in a type parameter (in which case you
1041   should specify ``representational`` explicitly.)  Unlike
1042   regular data types, we do *not* assume that abstract
1043   data types are representationally injective: if we have
1044   ``Coercible (T a) (T b)``, and ``T`` has role ``nominal``,
1045   this does not imply that ``a ~ b``.
1046
1047 - A class declarations can either be abstract or concrete.  An
1048   abstract class is one with no superclasses or class methods::
1049
1050     signature A where
1051         class Key k
1052
1053   It can be implemented in any way, with any set of superclasses
1054   and methods; however, modules depending on an abstract class
1055   are not permitted to define instances (as of GHC 8.2, this
1056   restriction is not checked, see :ghc-ticket:`13086`.)
1057   These declarations can be implemented by type synonyms
1058   of kind ``Constraint``; this can be useful if you want to parametrize
1059   over a constraint in functions.  For example, with the
1060   ``ConstraintKinds`` extension, this type synonym is a valid
1061   implementation of the signature above::
1062
1063     module A where
1064         type Key = Eq
1065
1066   A concrete class specifies its superclasses, methods,
1067   default method signatures (but not their implementations)
1068   and a ``MINIMAL`` pragma.  Unlike regular Haskell classes,
1069   you don't have to explicitly declare a default for a method
1070   to make it optional vis-a-vis the ``MINIMAL`` pragma.
1071
1072   When merging class declarations, we require that the superclasses
1073   and methods match exactly; however, ``MINIMAL`` pragmas are logically
1074   ORed together, and a method with a default signature will merge
1075   successfully against one that does not.
1076
1077 - You can include instance declarations as in Haskell; just omit the
1078   "where" part.  An instance declaration need not be implemented directly;
1079   if an instance can be derived based on instances in the environment,
1080   it is considered implemented.  For example, the following signature::
1081
1082     signature A where
1083         data Str
1084         instance Eq Str
1085
1086   is considered implemented by the following module, since there
1087   are instances of ``Eq`` for ``[]`` and ``Char`` which can be combined
1088   to form an instance ``Eq [Char]``::
1089
1090     module A where
1091         type Str = [Char]
1092
1093   Unlike other declarations, for which only the entities declared
1094   in a signature file are brought into scope, instances from the
1095   implementation are always brought into scope, even if they were
1096   not declared in the signature file.  This means that a module may
1097   typecheck against a signature, but not against a matching
1098   implementation.  You can avoid situations like this by never
1099   defining orphan instances inside a package that has signatures.
1100
1101   Instance declarations are only merged if their heads are exactly
1102   the same, so it is possible to get into a situation where GHC
1103   thinks that instances in a signature are overlapping, even if
1104   they are implemented in a non-overlapping way.  If this is
1105   giving you problems give us a shout.
1106
1107 - Any orphan instances which are brought into scope by an import
1108   from a signature are unconditionally considered in scope, even
1109   if the eventual implementing module doesn't actually import the
1110   same orphans.
1111
1112 Known limitations:
1113
1114 - Pattern synonyms are not supported.
1115
1116 - Algebraic data types specified in a signature cannot be implemented using
1117   pattern synonyms.  See :ghc-ticket:`12717`
1118
1119 .. _using-make:
1120
1121 Using ``make``
1122 --------------
1123
1124 .. index::
1125    single: make; building programs with
1126
1127 It is reasonably straightforward to set up a ``Makefile`` to use with
1128 GHC, assuming you name your source files the same as your modules. Thus:
1129
1130 .. code-block:: makefile
1131
1132     HC      = ghc
1133     HC_OPTS = -cpp $(EXTRA_HC_OPTS)
1134
1135     SRCS = Main.lhs Foo.lhs Bar.lhs
1136     OBJS = Main.o   Foo.o   Bar.o
1137
1138     .SUFFIXES : .o .hs .hi .lhs .hc .s
1139
1140     cool_pgm : $(OBJS)
1141             rm -f $@
1142             $(HC) -o $@ $(HC_OPTS) $(OBJS)
1143
1144     # Standard suffix rules
1145     .o.hi:
1146             @:
1147
1148     .lhs.o:
1149             $(HC) -c $< $(HC_OPTS)
1150
1151     .hs.o:
1152             $(HC) -c $< $(HC_OPTS)
1153
1154     .o-boot.hi-boot:
1155             @:
1156
1157     .lhs-boot.o-boot:
1158             $(HC) -c $< $(HC_OPTS)
1159
1160     .hs-boot.o-boot:
1161             $(HC) -c $< $(HC_OPTS)
1162
1163     # Inter-module dependencies
1164     Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
1165     Main.o Main.hc Main.s : Foo.hi Baz.hi   # Main imports Foo and Baz
1166
1167 .. note::
1168     Sophisticated :command:`make` variants may achieve some of the above more
1169     elegantly. Notably, :command:`gmake`\'s pattern rules let you write the more
1170     comprehensible:
1171
1172     .. code-block:: make
1173
1174         %.o : %.lhs
1175                 $(HC) -c $< $(HC_OPTS)
1176
1177     What we've shown should work with any ``make``.
1178
1179 Note the cheesy ``.o.hi`` rule: It records the dependency of the
1180 interface (``.hi``) file on the source. The rule says a ``.hi`` file can
1181 be made from a ``.o`` file by doing…nothing. Which is true.
1182
1183 Note that the suffix rules are all repeated twice, once for normal
1184 Haskell source files, and once for ``hs-boot`` files (see
1185 :ref:`mutual-recursion`).
1186
1187 Note also the inter-module dependencies at the end of the Makefile,
1188 which take the form
1189
1190 .. code-block:: make
1191
1192     Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
1193
1194 They tell ``make`` that if any of ``Foo.o``, ``Foo.hc`` or ``Foo.s``
1195 have an earlier modification date than ``Baz.hi``, then the out-of-date
1196 file must be brought up to date. To bring it up to date, ``make`` looks
1197 for a rule to do so; one of the preceding suffix rules does the job
1198 nicely. These dependencies can be generated automatically by ``ghc``;
1199 see :ref:`makefile-dependencies`
1200
1201 .. _makefile-dependencies:
1202
1203 Dependency generation
1204 ---------------------
1205
1206 .. index::
1207    single: dependencies in Makefiles
1208    single: Makefile dependencies
1209
1210 Putting inter-dependencies of the form ``Foo.o : Bar.hi`` into your
1211 ``Makefile`` by hand is rather error-prone. Don't worry, GHC has support
1212 for automatically generating the required dependencies. Add the
1213 following to your ``Makefile``:
1214
1215 .. code-block:: make
1216
1217     depend :
1218             ghc -dep-suffix '' -M $(HC_OPTS) $(SRCS)
1219
1220 Now, before you start compiling, and any time you change the ``imports``
1221 in your program, do ``make depend`` before you do ``make cool_pgm``. The command
1222 ``ghc -M`` will append the needed dependencies to your ``Makefile``.
1223
1224 In general, ``ghc -M Foo`` does the following. For each module ``M`` in
1225 the set ``Foo`` plus all its imports (transitively), it adds to the
1226 Makefile:
1227
1228 -  A line recording the dependence of the object file on the source
1229    file.
1230
1231    .. code-block:: make
1232
1233        M.o : M.hs
1234
1235    (or ``M.lhs`` if that is the filename you used).
1236
1237 -  For each import declaration ``import X`` in ``M``, a line recording
1238    the dependence of ``M`` on ``X``:
1239
1240    .. code-block:: make
1241
1242        M.o : X.hi
1243
1244 -  For each import declaration ``import {-# SOURCE #-} X`` in ``M``, a
1245    line recording the dependence of ``M`` on ``X``:
1246
1247    .. code-block:: make
1248
1249        M.o : X.hi-boot
1250
1251    (See :ref:`mutual-recursion` for details of ``hi-boot`` style
1252    interface files.)
1253
1254 If ``M`` imports multiple modules, then there will be multiple lines
1255 with ``M.o`` as the target.
1256
1257 There is no need to list all of the source files as arguments to the
1258 ``ghc -M`` command; ``ghc`` traces the dependencies, just like
1259 ``ghc --make`` (a new feature in GHC 6.4).
1260
1261 Note that ``ghc -M`` needs to find a *source file* for each module in
1262 the dependency graph, so that it can parse the import declarations and
1263 follow dependencies. Any pre-compiled modules without source files must
1264 therefore belong to a package [1]_.
1265
1266 By default, ``ghc -M`` generates all the dependencies, and then
1267 concatenates them onto the end of ``makefile`` (or ``Makefile`` if
1268 ``makefile`` doesn't exist) bracketed by the lines
1269 "``# DO NOT DELETE: Beginning of Haskell dependencies``" and
1270 "``# DO NOT DELETE: End of Haskell dependencies``". If these lines
1271 already exist in the ``makefile``, then the old dependencies are deleted
1272 first.
1273
1274 Don't forget to use the same ``-package`` options on the ``ghc -M``
1275 command line as you would when compiling; this enables the dependency
1276 generator to locate any imported modules that come from packages. The
1277 package modules won't be included in the dependencies generated, though
1278 (but see the ``-include-pkg-deps`` option below).
1279
1280 The dependency generation phase of GHC can take some additional options,
1281 which you may find useful. The options which affect dependency
1282 generation are:
1283
1284 .. ghc-flag:: -ddump-mod-cycles
1285     :shortdesc: Dump module cycles
1286     :type: dynamic
1287     :category:
1288
1289     Display a list of the cycles in the module graph. This is useful
1290     when trying to eliminate such cycles.
1291
1292 .. ghc-flag:: -v2
1293     :noindex:
1294
1295     Print a full list of the module dependencies to stdout. (This is the
1296     standard verbosity flag, so the list will also be displayed with
1297     ``-v3`` and ``-v4``; see :ref:`options-help`.)
1298
1299 .. ghc-flag:: -dep-makefile ⟨file⟩
1300     :shortdesc: Use ⟨file⟩ as the makefile
1301     :type: dynamic
1302     :category:
1303
1304     Use ⟨file⟩ as the makefile, rather than ``makefile`` or
1305     ``Makefile``. If ⟨file⟩ doesn't exist, ``mkdependHS`` creates it. We
1306     often use ``-dep-makefile .depend`` to put the dependencies in
1307     ``.depend`` and then ``include`` the file ``.depend`` into
1308     ``Makefile``.
1309
1310 .. ghc-flag:: -dep-suffix ⟨suffix⟩
1311     :shortdesc: Make dependencies that declare that files with suffix
1312         ``.⟨suf⟩⟨osuf⟩`` depend on interface files with suffix ``.⟨suf⟩hi``
1313     :type: dynamic
1314     :category:
1315
1316     Make dependencies that declare that files with suffix
1317     ``.⟨suf⟩⟨osuf⟩`` depend on interface files with suffix
1318     ``.⟨suf⟩hi``, or (for ``{-# SOURCE #-}`` imports) on ``.hi-boot``.
1319     Multiple ``-dep-suffix`` flags are permitted. For example,
1320     ``-dep-suffix a_ -dep-suffix b_`` will make dependencies for ``.hs``
1321     on ``.hi``, ``.a_hs`` on ``.a_hi``, and ``.b_hs`` on ``.b_hi``.
1322     Note that you must provide at least one suffix; if you do not want a suffix
1323     then pass ``-dep-suffix ''``.
1324
1325 .. ghc-flag:: --exclude-module=⟨file⟩
1326     :shortdesc: Regard ``⟨file⟩`` as "stable"; i.e., exclude it from having
1327         dependencies on it.
1328     :type: dynamic
1329     :category:
1330
1331     Regard ``⟨file⟩`` as "stable"; i.e., exclude it from having
1332     dependencies on it.
1333
1334 .. ghc-flag:: -include-pkg-deps
1335     :shortdesc: Regard modules imported from packages as unstable
1336     :type: dynamic
1337     :category:
1338
1339     Regard modules imported from packages as unstable, i.e., generate
1340     dependencies on any imported package modules (including ``Prelude``,
1341     and all other standard Haskell libraries). Dependencies are not
1342     traced recursively into packages; dependencies are only generated
1343     for home-package modules on external-package modules directly
1344     imported by the home package module. This option is normally only
1345     used by the various system libraries.
1346
1347 .. _orphan-modules:
1348
1349 Orphan modules and instance declarations
1350 ----------------------------------------
1351
1352 Haskell specifies that when compiling module ``M``, any instance declaration
1353 in any module "below" ``M`` is visible. (Module ``A`` is "below" ``M`` if ``A`` is
1354 imported directly by ``M``, or if ``A`` is below a module that ``M`` imports
1355 directly.) In principle, GHC must therefore read the interface files of
1356 every module below ``M``, just in case they contain an instance declaration
1357 that matters to ``M``. This would be a disaster in practice, so GHC tries to
1358 be clever.
1359
1360 In particular, if an instance declaration is in the same module as the
1361 definition of any type or class mentioned in the *head* of the instance
1362 declaration (the part after the "``=>``"; see :ref:`instance-rules`), then GHC
1363 has to visit that interface file anyway. Example: ::
1364
1365       module A where
1366         instance C a => D (T a) where ...
1367         data T a = ...
1368
1369 The instance declaration is only relevant if the type ``T`` is in use, and
1370 if so, GHC will have visited ``A``\'s interface file to find ``T``\'s definition.
1371
1372 The only problem comes when a module contains an instance declaration
1373 and GHC has no other reason for visiting the module. Example: ::
1374
1375       module Orphan where
1376         instance C a => D (T a) where ...
1377         class C a where ...
1378
1379 Here, neither ``D`` nor ``T`` is declared in module ``Orphan``. We call such modules
1380 "orphan modules". GHC identifies orphan modules, and visits the
1381 interface file of every orphan module below the module being compiled.
1382 This is usually wasted work, but there is no avoiding it. You should
1383 therefore do your best to have as few orphan modules as possible.
1384
1385 Functional dependencies complicate matters. Suppose we have: ::
1386
1387       module B where
1388         instance E T Int where ...
1389         data T = ...
1390
1391 Is this an orphan module? Apparently not, because ``T`` is declared in
1392 the same module. But suppose class ``E`` had a functional dependency: ::
1393
1394       module Lib where
1395         class E x y | y -> x where ...
1396
1397 Then in some importing module ``M``, the constraint ``(E a Int)`` should be
1398 "improved" by setting ``a = T``, *even though there is no explicit
1399 mention* of ``T`` in ``M``.
1400
1401 These considerations lead to the following definition of an orphan
1402 module:
1403
1404 -  An *orphan module* orphan module contains at least one *orphan
1405    instance* or at least one *orphan rule*.
1406
1407 -  An instance declaration in a module ``M`` is an *orphan instance* if
1408    orphan instance
1409
1410    -  The class of the instance declaration is not declared in ``M``, and
1411
1412    -  *Either* the class has no functional dependencies, and none of the
1413       type constructors in the instance head is declared in ``M``; *or*
1414       there is a functional dependency for which none of the type
1415       constructors mentioned in the *non-determined* part of the
1416       instance head is defined in ``M``.
1417
1418    Only the instance head counts. In the example above, it is not good
1419    enough for ``C``\'s declaration to be in module ``A``; it must be the
1420    declaration of ``D`` or ``T``.
1421
1422 -  A rewrite rule in a module ``M`` is an *orphan rule* orphan rule if none
1423    of the variables, type constructors, or classes that are free in the
1424    left hand side of the rule are declared in ``M``.
1425
1426 If you use the flag :ghc-flag:`-Worphans`, GHC will warn you if you are
1427 creating an orphan module. Like any warning, you can switch the warning
1428 off with :ghc-flag:`-Wno-orphans <-Worphans>`, and :ghc-flag:`-Werror` will make
1429 the compilation fail if the warning is issued.
1430
1431 You can identify an orphan module by looking in its interface file, ``M.hi``,
1432 using the :ghc-flag:`--show-iface ⟨file⟩` :ref:`mode <modes>`. If there is a
1433 ``[orphan module]`` on the first line, GHC considers it an orphan module.
1434
1435 .. [1]
1436    This is a change in behaviour relative to 6.2 and earlier.