Include CPP preprocessor dependencies in -M output
[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
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
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     Please also note that when doing incremental compilation, this directory is
264     where GHC looks into to find object files from previous builds.
265
266 .. ghc-flag:: -ohi ⟨file⟩
267     :shortdesc: set the filename in which to put the interface
268     :type: dynamic
269     :category:
270
271     The interface output may be directed to another file
272     ``bar2/Wurble.iface`` with the option ``-ohi bar2/Wurble.iface``
273     (not recommended).
274
275     .. warning::
276        If you redirect the interface file somewhere that GHC can't
277        find it, then the recompilation checker may get confused (at the
278        least, you won't get any recompilation avoidance). We recommend
279        using a combination of ``-hidir`` and ``-hisuf`` options instead, if
280        possible.
281
282     To avoid generating an interface at all, you could use this option
283     to redirect the interface into the bit bucket: ``-ohi /dev/null``,
284     for example.
285
286 .. ghc-flag:: -hidir ⟨dir⟩
287     :shortdesc: set directory for interface files
288     :type: dynamic
289     :category:
290
291     Redirects all generated interface files into ⟨dir⟩, instead of the
292     default.
293
294     Please also note that when doing incremental compilation (by ``ghc --make``
295     or ``ghc -c``), this directory is where GHC looks into to find interface
296     files.
297
298 .. ghc-flag:: -hiedir ⟨dir⟩
299     :shortdesc: set directory for extended interface files
300     :type: dynamic
301     :category:
302
303     Redirects all generated extended interface files into ⟨dir⟩, instead of
304     the default.
305
306     Please also note that when doing incremental compilation (by ``ghc --make``
307     or ``ghc -c``), this directory is where GHC looks into to find extended
308     interface files.
309
310 .. ghc-flag:: -stubdir ⟨dir⟩
311     :shortdesc: redirect FFI stub files
312     :type: dynamic
313     :category:
314
315     Redirects all generated FFI stub files into ⟨dir⟩. Stub files are
316     generated when the Haskell source contains a ``foreign export`` or
317     ``foreign import "&wrapper"`` declaration (see
318     :ref:`foreign-export-ghc`). The ``-stubdir`` option behaves in
319     exactly the same way as ``-odir`` and ``-hidir`` with respect to
320     hierarchical modules.
321
322 .. ghc-flag:: -dumpdir ⟨dir⟩
323     :shortdesc: redirect dump files
324     :type: dynamic
325     :category:
326
327     Redirects all dump files into ⟨dir⟩. Dump files are generated when
328     ``-ddump-to-file`` is used with other ``-ddump-*`` flags.
329
330 .. ghc-flag:: -outputdir ⟨dir⟩
331     :shortdesc: set output directory
332     :type: dynamic
333     :category:
334
335     The ``-outputdir`` option is shorthand for the combination of
336     :ghc-flag:`-odir ⟨dir⟩`, :ghc-flag:`-hidir ⟨dir⟩`, :ghc-flag:`-stubdir
337     ⟨dir⟩` and :ghc-flag:`-dumpdir ⟨dir⟩`.
338
339 .. ghc-flag:: -osuf ⟨suffix⟩
340     :shortdesc: set the output file suffix
341     :type: dynamic
342     :category:
343
344     The ``-osuf`` ⟨suffix⟩ will change the ``.o`` file suffix for object
345     files to whatever you specify. We use this when compiling libraries,
346     so that objects for the profiling versions of the libraries don't
347     clobber the normal ones.
348
349 .. ghc-flag:: -hisuf ⟨suffix⟩
350     :shortdesc: set the suffix to use for interface files
351     :type: dynamic
352     :category:
353
354     Similarly, the ``-hisuf`` ⟨suffix⟩ will change the ``.hi`` file
355     suffix for non-system interface files (see :ref:`hi-options`).
356
357     The ``-hisuf``/``-osuf`` game is particularly useful if you want to
358     compile a program both with and without profiling, in the same
359     directory. You can say:
360
361     .. code-block:: none
362
363         ghc ...
364
365     to get the ordinary version, and
366
367     .. code-block:: none
368
369         ghc ... -osuf prof.o -hisuf prof.hi -prof -fprof-auto
370
371     to get the profiled version.
372
373 .. ghc-flag:: -hiesuf ⟨suffix⟩
374     :shortdesc: set the suffix to use for extended interface files
375     :type: dynamic
376
377     The ``-hiesuf`` ⟨suffix⟩ will change the ``.hie`` file suffix for
378     extended interface files to whatever you specify.
379
380 .. ghc-flag:: -hcsuf ⟨suffix⟩
381     :shortdesc: set the suffix to use for intermediate C files
382     :type: dynamic
383     :category:
384
385     Finally, the option ``-hcsuf`` ⟨suffix⟩ will change the ``.hc`` file
386     suffix for compiler-generated intermediate C files.
387
388 .. _keeping-intermediates:
389
390 Keeping Intermediate Files
391 --------------------------
392
393 .. index::
394    single: intermediate files, saving
395    single: .hc files, saving
396    single: .ll files, saving
397    single: .s files, saving
398
399 The following options are useful for keeping (or not keeping) certain
400 intermediate files around, when normally GHC would throw these away after
401 compilation:
402
403 .. ghc-flag:: -keep-hc-file
404               -keep-hc-files
405     :shortdesc: Retain intermediate ``.hc`` files.
406     :type: dynamic
407     :category: keep-intermediates
408
409     Keep intermediate ``.hc`` files when doing ``.hs``-to-``.o``
410     compilations via :ref:`C <c-code-gen>` (Note: ``.hc`` files are only
411     generated by :ref:`unregisterised <unreg>` compilers).
412
413 .. ghc-flag:: -keep-hi-files
414     :shortdesc: Retain intermediate ``.hi`` files (the default).
415     :type: dynamic
416     :reverse: -no-keep-hi-files
417     :category: keep-intermediates
418
419     .. index::
420        single: temporary files; keeping
421
422     Keep intermediate ``.hi`` files. This is the default. You may use
423     ``-no-keep-hi-files`` if you are not interested in the ``.hi`` files.
424
425 .. ghc-flag:: -keep-hscpp-file
426               -keep-hscpp-files
427     :shortdesc: Retain intermediate ``.hscpp`` files.
428     :type: dynamic
429     :category: keep-intermediates
430
431     .. index::
432        single: temporary files; keeping
433
434     Keep the output of the ``CPP`` pre-processor phase as ``.hscpp`` files.
435     A ``.hscpp`` file is only created, if a module gets compiled and uses the
436     C pre-processor.
437
438 .. ghc-flag:: -keep-llvm-file
439               -keep-llvm-files
440     :shortdesc: Retain intermediate LLVM ``.ll`` files.
441         Implies :ghc-flag:`-fllvm`.
442     :type: dynamic
443     :category: keep-intermediates
444
445     :implies: :ghc-flag:`-fllvm`
446
447     Keep intermediate ``.ll`` files when doing ``.hs``-to-``.o``
448     compilations via :ref:`LLVM <llvm-code-gen>` (Note: ``.ll`` files
449     aren't generated when using the native code generator, you may need
450     to use :ghc-flag:`-fllvm` to force them to be produced).
451
452 .. ghc-flag:: -keep-o-files
453     :shortdesc: Retain intermediate ``.o`` files (the default).
454     :type: dynamic
455     :reverse: -no-keep-o-files
456     :category: keep-intermediates
457
458     .. index::
459        single: temporary files; keeping
460
461     Keep intermediate ``.o`` files. This is the default. You may use
462     ``-no-keep-o-files`` if you are not interested in the ``.o`` files.
463
464 .. ghc-flag:: -keep-s-file
465               -keep-s-files
466     :shortdesc: Retain intermediate ``.s`` files.
467     :type: dynamic
468     :category: keep-intermediates
469
470     Keep intermediate ``.s`` files.
471
472 .. ghc-flag:: -keep-tmp-files
473     :shortdesc: Retain all intermediate temporary files.
474     :type: dynamic
475     :category: keep-intermediates
476
477     .. index::
478        single: temporary files; keeping
479
480     Instructs the GHC driver not to delete any of its temporary files,
481     which it normally keeps in ``/tmp`` (or possibly elsewhere; see
482     :ref:`temp-files`). Running GHC with ``-v`` will show you what
483     temporary files were generated along the way.
484
485 .. _temp-files:
486
487 Redirecting temporary files
488 ---------------------------
489
490 .. index::
491    single: temporary files; redirecting
492
493 .. ghc-flag:: -tmpdir ⟨dir⟩
494     :shortdesc: set the directory for temporary files
495     :type: dynamic
496     :category: temp-files
497
498     If you have trouble because of running out of space in ``/tmp`` (or
499     wherever your installation thinks temporary files should go), you
500     may use the :ghc-flag:`-tmpdir ⟨dir⟩` option option to specify an
501     alternate directory. For example, ``-tmpdir .`` says to put temporary files
502     in the current working directory.
503
504     .. index::
505         single: TMPDIR environment variable
506
507     Alternatively, use your :envvar:`TMPDIR` environment variable. Set it to the
508     name of the directory where temporary files should be put. GCC and other
509     programs will honour the :envvar:`TMPDIR` variable as well.
510
511 .. _hi-options:
512
513 Other options related to interface files
514 ----------------------------------------
515
516 .. index::
517    single: interface files, options
518
519 .. ghc-flag:: -ddump-hi
520     :shortdesc: Dump the new interface to stdout
521     :type: dynamic
522     :category: interface-files
523
524     Dumps the new interface to standard output.
525
526 .. ghc-flag:: -ddump-hi-diffs
527     :shortdesc: Show the differences vs. the old interface
528     :type: dynamic
529     :category: interface-files
530
531     The compiler does not overwrite an existing ``.hi`` interface file
532     if the new one is the same as the old one; this is friendly to
533     :command:`make`. When an interface does change, it is often enlightening to
534     be informed. The :ghc-flag:`-ddump-hi-diffs` option will make GHC report the
535     differences between the old and new ``.hi`` files.
536
537 .. ghc-flag:: -ddump-minimal-imports
538     :shortdesc: Dump a minimal set of imports
539     :type: dynamic
540     :category: interface-files
541
542     Dump to the file :file:`{M}.imports` (where ⟨M⟩ is the name of the module
543     being compiled) a "minimal" set of import declarations. The
544     directory where the ``.imports`` files are created can be controlled
545     via the :ghc-flag:`-dumpdir ⟨dir⟩` option.
546
547     You can safely replace all the import declarations in :file:`{M}.hs` with
548     those found in its respective ``.imports`` file. Why would you want
549     to do that? Because the "minimal" imports (a) import everything
550     explicitly, by name, and (b) import nothing that is not required. It
551     can be quite painful to maintain this property by hand, so this flag
552     is intended to reduce the labour.
553
554 .. ghc-flag:: --show-iface ⟨file⟩
555     :shortdesc: See :ref:`modes`.
556     :type: mode
557     :category: interface-files
558
559     where ⟨file⟩ is the name of an interface file, dumps the contents of
560     that interface in a human-readable format. See :ref:`modes`.
561
562 .. _hie-options:
563
564 Options related to extended interface files
565 -------------------------------------------
566
567 .. index::
568    single: extended interface files, options
569
570 GHC builds up a wealth of information about a Haskell source file as it compiles
571 it. Extended interface files are a way of persisting some of this information to
572 disk so that external tools, such as IDE's, can avoid parsing, typechecking, and
573 renaming all over again. These files contain
574
575   * a simplified AST
576
577        * nodes are annotated with source positions and types
578        * identifiers are annotated with scope information
579
580   * the raw bytes of the initial Haskell source
581
582 The GHC API exposes functions for reading and writing these files.
583
584 .. ghc-flag:: -fwrite-ide-info
585     :shortdesc: Write out extended interface files
586     :type: dynamic
587     :category: extended-interface-files
588
589     Writes out extended interface files alongisde regular enterface files.
590     Just like regular interface files, GHC has a recompilation check to detect
591     out of date or missing extended interface files.
592
593 .. ghc-flag:: -fvalidate-ide-info
594     :shortdesc: Perform some sanity checks on the extended interface files
595     :type: dynamic
596     :category: extended-interface-files
597
598     Runs a series of sanity checks and lints on the extended interface files
599     that are being written out. These include testing things properties such as
600     variables not occuring outside of their expected scopes.
601
602 The format in which GHC currently stores its typechecked AST, makes it costly
603 to collect the types for some expressions nodes. For the sake of performance,
604 GHC currently chooses to skip over these, so not all expression nodes should be
605 expected to have type information on them. See :ghc-ticket:`16233` for more.
606
607 .. _recomp:
608
609 The recompilation checker
610 -------------------------
611
612 .. index::
613    single: recompilation checker
614
615 .. ghc-flag:: -fforce-recomp
616     :shortdesc: Turn off recompilation checking. This is implied by any
617         ``-ddump-X`` option when compiling a single file
618         (i.e. when using :ghc-flag:`-c`).
619     :type: dynamic
620     :reverse: -fno-force-recomp
621     :category: recompilation
622
623     Turn off recompilation checking (which is on by default).
624     Recompilation checking normally stops compilation early, leaving an
625     existing ``.o`` file in place, if it can be determined that the
626     module does not need to be recompiled.
627
628 .. ghc-flag:: -fignore-optim-changes
629     :shortdesc: Do not recompile modules just to match changes to
630         optimisation flags. This is especially useful for avoiding
631         recompilation when using GHCi, and is enabled by default for
632         GHCi.
633     :type: dynamic
634     :reverse: -fno-ignore-optim-changes
635     :category: recompilation
636
637 .. ghc-flag:: -fignore-hpc-changes
638     :shortdesc: Do not recompile modules just to match changes to
639         HPC flags. This is especially useful for avoiding recompilation
640         when using GHCi, and is enabled by default for GHCi.
641     :type: dynamic
642     :reverse: -fno-ignore-hpc-changes
643     :category: recompilation
644
645 In the olden days, GHC compared the newly-generated ``.hi`` file with
646 the previous version; if they were identical, it left the old one alone
647 and didn't change its modification date. In consequence, importers of a
648 module with an unchanged output ``.hi`` file were not recompiled.
649
650 This doesn't work any more. Suppose module ``C`` imports module ``B``,
651 and ``B`` imports module ``A``. So changes to module ``A`` might require
652 module ``C`` to be recompiled, and hence when ``A.hi`` changes we should
653 check whether ``C`` should be recompiled. However, the dependencies of
654 ``C`` will only list ``B.hi``, not ``A.hi``, and some changes to ``A``
655 (changing the definition of a function that appears in an inlining of a
656 function exported by ``B``, say) may conceivably not change ``B.hi`` one
657 jot. So now…
658
659 GHC calculates a fingerprint (in fact an MD5 hash) of each interface
660 file, and of each declaration within the interface file. It also keeps
661 in every interface file a list of the fingerprints of everything it used
662 when it last compiled the file. If the source file's modification date
663 is earlier than the ``.o`` file's date (i.e. the source hasn't changed
664 since the file was last compiled), and the recompilation checking is on,
665 GHC will be clever. It compares the fingerprints on the things it needs
666 this time with the fingerprints on the things it needed last time
667 (gleaned from the interface file of the module being compiled); if they
668 are all the same it stops compiling early in the process saying
669 “Compilation IS NOT required”. What a beautiful sight!
670
671 You can read about :ghc-wiki:`how all this works <commentary/compiler/recompilation-avoidance>` in the GHC commentary.
672
673 .. _mutual-recursion:
674
675 How to compile mutually recursive modules
676 -----------------------------------------
677
678 .. index::
679    single: module system, recursion
680    single: recursion, between modules
681
682 GHC supports the compilation of mutually recursive modules. This section
683 explains how.
684
685 Every cycle in the module import graph must be broken by a ``hs-boot``
686 file. Suppose that modules ``A.hs`` and ``B.hs`` are Haskell source
687 files, thus: ::
688
689     module A where
690         import B( TB(..) )
691
692         newtype TA = MkTA Int
693
694         f :: TB -> TA
695         f (MkTB x) = MkTA x
696
697     module B where
698         import {-# SOURCE #-} A( TA(..) )
699
700         data TB = MkTB !Int
701
702         g :: TA -> TB
703         g (MkTA x) = MkTB x
704
705 .. index::
706    single: ``hs-boot`` files
707    single: importing, ``hi-boot`` files
708
709 Here ``A`` imports ``B``, but ``B`` imports ``A`` with a
710 ``{-# SOURCE #-}`` pragma, which breaks the circular dependency. Every
711 loop in the module import graph must be broken by a ``{-# SOURCE #-}``
712 import; or, equivalently, the module import graph must be acyclic if
713 ``{-# SOURCE #-}`` imports are ignored.
714
715 For every module ``A.hs`` that is ``{-# SOURCE #-}``-imported in this
716 way there must exist a source file ``A.hs-boot``. This file contains an
717 abbreviated version of ``A.hs``, thus: ::
718
719     module A where
720         newtype TA = MkTA Int
721
722 To compile these three files, issue the following commands:
723
724 .. code-block:: none
725
726       ghc -c A.hs-boot    -- Produces A.hi-boot, A.o-boot
727       ghc -c B.hs         -- Consumes A.hi-boot, produces B.hi, B.o
728       ghc -c A.hs         -- Consumes B.hi, produces A.hi, A.o
729       ghc -o foo A.o B.o  -- Linking the program
730
731 There are several points to note here:
732
733 -  The file ``A.hs-boot`` is a programmer-written source file. It must
734    live in the same directory as its parent source file ``A.hs``.
735    Currently, if you use a literate source file ``A.lhs`` you must also
736    use a literate boot file, ``A.lhs-boot``; and vice versa.
737
738 -  A ``hs-boot`` file is compiled by GHC, just like a ``hs`` file:
739
740    .. code-block:: none
741
742          ghc -c A.hs-boot
743
744    When a hs-boot file ``A.hs-boot`` is compiled, it is checked for
745    scope and type errors. When its parent module ``A.hs`` is compiled,
746    the two are compared, and an error is reported if the two are
747    inconsistent.
748
749 -  Just as compiling ``A.hs`` produces an interface file ``A.hi``, and
750    an object file ``A.o``, so compiling ``A.hs-boot`` produces an
751    interface file ``A.hi-boot``, and a pseudo-object file ``A.o-boot``:
752
753    -  The pseudo-object file ``A.o-boot`` is empty (don't link it!), but
754       it is very useful when using a Makefile, to record when the
755       ``A.hi-boot`` was last brought up to date (see :ref:`using-make`).
756
757    -  The ``hi-boot`` generated by compiling a ``hs-boot`` file is in
758       the same machine-generated binary format as any other
759       GHC-generated interface file (e.g. ``B.hi``). You can display its
760       contents with ``ghc --show-iface``. If you specify a directory for
761       interface files, the ``-ohidir`` flag, then that affects ``hi-boot`` files
762       too.
763
764 -  If hs-boot files are considered distinct from their parent source
765    files, and if a ``{-# SOURCE #-}`` import is considered to refer to
766    the hs-boot file, then the module import graph must have no cycles.
767    The command ``ghc -M`` will report an error if a cycle is found.
768
769 -  A module ``M`` that is ``{-# SOURCE #-}``\-imported in a program will
770    usually also be ordinarily imported elsewhere. If not, ``ghc --make``
771    automatically adds ``M`` to the set of modules it tries to compile
772    and link, to ensure that ``M``\'s implementation is included in the
773    final program.
774
775 A hs-boot file need only contain the bare minimum of information needed
776 to get the bootstrapping process started. For example, it doesn't need
777 to contain declarations for *everything* that module ``A`` exports, only
778 the things required by the module(s) that import ``A`` recursively.
779
780 A hs-boot file is written in a subset of Haskell:
781
782 -  The module header (including the export list), and import statements,
783    are exactly as in Haskell, and so are the scoping rules. Hence, to
784    mention a non-Prelude type or class, you must import it.
785
786 -  There must be no value declarations, but there can be type signatures
787    for values. For example: ::
788
789         double :: Int -> Int
790
791 -  Fixity declarations are exactly as in Haskell.
792
793 -  Vanilla type synonym declarations are exactly as in Haskell.
794
795 -  Open type and data family declarations are exactly as in Haskell.
796
797 -  A closed type family may optionally omit its equations, as in the
798    following example: ::
799
800         type family ClosedFam a where ..
801
802    The ``..`` is meant literally -- you should write two dots in your
803    file. Note that the ``where`` clause is still necessary to
804    distinguish closed families from open ones. If you give any equations
805    of a closed family, you must give all of them, in the same order as
806    they appear in the accompanying Haskell file.
807
808 -  A data type declaration can either be given in full, exactly as in
809    Haskell, or it can be given abstractly, by omitting the '=' sign and
810    everything that follows. For example: ::
811
812         data T a b
813
814    In a *source* program this would declare TA to have no constructors
815    (a GHC extension: see :ref:`nullary-types`), but in an hi-boot file
816    it means "I don't know or care what the constructors are". This is
817    the most common form of data type declaration, because it's easy to
818    get right. You *can* also write out the constructors but, if you do
819    so, you must write it out precisely as in its real definition.
820
821    If you do not write out the constructors, you may need to give a kind
822    annotation (:ref:`kinding`), to tell GHC the kind of the type
823    variable, if it is not "\*". (In source files, this is worked out
824    from the way the type variable is used in the constructors.) For
825    example: ::
826
827         data R (x :: * -> *) y
828
829    You cannot use ``deriving`` on a data type declaration; write an
830    ``instance`` declaration instead.
831
832 -  Class declarations is exactly as in Haskell, except that you may not
833    put default method declarations. You can also omit all the
834    superclasses and class methods entirely; but you must either omit
835    them all or put them all in.
836
837 -  You can include instance declarations just as in Haskell; but omit
838    the "where" part.
839
840 -  The default role for abstract datatype parameters is now
841    representational. (An abstract datatype is one with no constructors
842    listed.) To get another role, use a role annotation. (See
843    :ref:`roles`.)
844
845 .. _module-signatures:
846
847 Module signatures
848 -----------------
849
850 .. index::
851      single: signature files; Backpack; hsig files
852
853 GHC 8.2 supports module signatures (``hsig`` files), which allow you to
854 write a signature in place of a module implementation, deferring the
855 choice of implementation until a later point in time.  This feature is
856 not intended to be used without `Cabal
857 <http://www.haskell.org/cabal/>`__; this manual entry will focus
858 on the syntax and semantics of signatures.
859
860 To start with an example, suppose you had a module ``A`` which made use of some
861 string operations.  Using normal module imports, you would only
862 be able to pick a particular implementation of strings::
863
864     module Str where
865         type Str = String
866
867         empty :: Str
868         empty = ""
869
870         toString :: Str -> String
871         toString s = s
872
873     module A where
874         import Str
875         z = toString empty
876
877 By replacing ``Str.hs`` with a signature ``Str.hsig``, ``A`` (and
878 any other modules in this package) are now parametrized by
879 a string implementation::
880
881     signature Str where
882         data Str
883         empty :: Str
884         toString :: Str -> String
885
886 We can typecheck ``A`` against this signature, or we can instantiate
887 ``Str`` with a module that provides the following declarations.  Refer
888 to Cabal's documentation for a more in-depth discussion on how to
889 instantiate signatures.
890
891 Module signatures actually consist of two closely related features:
892
893 - The ability to define an ``hsig`` file, containing type definitions
894   and type signature for values which can be used by modules that
895   import the signature, and must be provided by the eventual
896   implementing module, and
897
898 - The ability to *inherit* required signatures from packages we
899   depend upon, combining the signatures into a single merged
900   signature which reflects the requirements of any locally defined
901   signature, as well as the requirements of our dependencies.
902
903 A signature file is denoted by an ``hsig`` file; every required
904 signature must have an ``hsig`` file (even if it is an empty one),
905 including required signatures inherited from dependencies.  Signatures
906 can be imported using an ordinary ``import Sig`` declaration.
907
908 ``hsig`` files are written in a variant of Haskell similar
909 to ``hs-boot`` files, but with some slight changes:
910
911 - The header of a signature is ``signature A where ...`` (instead
912   of the usual ``module A where ...``).
913
914 - Import statements and scoping rules are exactly as in Haskell.
915   To mention a non-Prelude type or class, you must import it.
916
917 - Unlike regular modules, the defined entities of
918   a signature include not only those written in the local
919   ``hsig`` file, but also those from inherited signatures
920   (as inferred from the :ghc-flag:`-package-id ⟨unit-id⟩` flags).
921   These entities are not considered in scope when typechecking
922   the local ``hsig`` file, but are available for import by
923   any module or signature which imports the signature.  The
924   one exception to this rule is the export list, described
925   below.
926
927   If a declaration occurs in multiple inherited signatures,
928   they will be *merged* together.  For values, we require
929   that the types from both signatures match exactly; however,
930   other declarations may merge in more interesting ways.
931   The merging operation in these cases has the effect of
932   textually replacing all occurrences of the old name with
933   a reference to the new, merged declaration.  For example,
934   if we have the following two signatures::
935
936     signature A where
937         data T
938         f :: T -> T
939
940     signature A where
941         data T = MkT
942         g :: T
943
944   the resulting merged signature would be::
945
946     signature A where
947         data T = MkT
948         f :: T -> T
949         g :: T
950
951 - If no export list is provided for a signature, the exports of
952   a signature are all of its defined entities merged with the
953   exports of all inherited signatures.
954
955   If you want to reexport an entity from a signature, you must
956   also include a ``module SigName`` export, so that all of the
957   entities defined in the signature are exported.  For example,
958   the following module exports both ``f`` and ``Int`` from
959   ``Prelude``::
960
961     signature A(module A, Int) where
962         import Prelude (Int)
963         f :: Int
964
965   Reexports merge with local declarations; thus, the signature above
966   would successfully merge with::
967
968     signature A where
969         data Int
970
971   The only permissible implementation of such a signature is a module
972   which reexports precisely the same entity::
973
974     module A (f, Int) where
975         import Prelude (Int)
976         f = 2 :: Int
977
978   Conversely, any entity requested by a signature can be provided
979   by a reexport from the implementing module.  This is different from
980   ``hs-boot`` files, which require every entity to be defined
981   locally in the implementing module.
982
983 - GHC has experimental support for *signature thinning*, which is used
984   when a signature has an explicit export list without a module export of the
985   signature itself.  In this case, the export list applies to the final export
986   list *after* merging, in particular, you may refer to entities which are not
987   declared in the body of the local ``hsig`` file.
988
989   The semantics in this case is that the set of required entities is defined
990   exclusively by its exports; if an entity is not mentioned in the export list,
991   it is not required.  The motivation behind this feature is to allow a library
992   author to provide an omnibus signature containing the type of every function
993   someone might want to use, while a client thins down the exports to the ones
994   they actually require.  For example, supposing that you have inherited a
995   signature for strings, you might write a local signature of this form, listing
996   only the entities that you need::
997
998     signature Str (Str, empty, append, concat) where
999         -- empty
1000
1001   A few caveats apply here.  First, it is illegal to export an entity
1002   which refers to a locally defined type which itself is not exported
1003   (GHC will report an error in this case).  Second, signatures which
1004   come from dependencies which expose modules cannot be thinned in this
1005   way (after all, the dependency itself may need the entity); these
1006   requirements are unconditionally exported.  Finally, any module
1007   reexports must refer to modules imported by the local signature
1008   (even if an inherited signature exported the module).
1009
1010   We may change the syntax and semantics of this feature in the future.
1011
1012 - The declarations and types from signatures of dependencies
1013   that will be merged in are not in scope when type checking
1014   an ``hsig`` file.  To refer to any such type, you must
1015   declare it yourself::
1016
1017     -- OK, assuming we inherited an A that defines T
1018     signature A (T) where
1019         -- empty
1020
1021     -- Not OK
1022     signature A (T, f) where
1023         f :: T -> T
1024
1025     -- OK
1026     signature A (T, f) where
1027         data T
1028         f :: T -> T
1029
1030 - There must be no value declarations, but there can be type signatures
1031   for values.  For example, we might define the signature::
1032
1033         signature A where
1034             double :: Int -> Int
1035
1036   A module implementing ``A`` would have to export the function
1037   ``double`` with a type definitionally equal to the signature.
1038   Note that this means you can't implement ``double`` using
1039   a polymorphic function ``double :: Num a => a -> a``.
1040
1041   Note that signature matching does check if *fixity* matches, so be
1042   sure specify fixity of ordinary identifiers if you intend to use them
1043   with backticks.
1044
1045 - Fixity, type synonym, open type/data family declarations
1046   are permitted as in normal Haskell.
1047
1048 - Closed type family declarations are permitted as in normal
1049   Haskell.  They can also be given abstractly, as in the
1050   following example::
1051
1052     type family ClosedFam a where ..
1053
1054   The ``..`` is meant literally -- you should write two dots in
1055   your file.  The ``where`` clause distinguishes closed families
1056   from open ones.
1057
1058 - A data type declaration can either be given in full, exactly
1059   as in Haskell, or it can be given abstractly, by omitting the '='
1060   sign and everything that follows.  For example: ::
1061
1062         signature A where
1063             data T a b
1064
1065   Abstract data types can be implemented not only with data
1066   declarations, but also newtypes and type synonyms (with the
1067   restriction that a type synonym must be fully eta-reduced,
1068   e.g., ``type T = ...`` to be accepted.)  For example,
1069   the following are all valid implementations of the T above::
1070
1071         -- Algebraic data type
1072         data T a b = MkT a b
1073
1074         -- Newtype
1075         newtype T a b = MkT (a, b)
1076
1077         -- Type synonym
1078         data T2 a b = MkT2 a a b b
1079         type T = T2
1080
1081   Data type declarations merge only with other data type
1082   declarations which match exactly, except abstract data,
1083   which can merge with ``data``, ``newtype`` or ``type``
1084   declarations.  Merges with type synonyms are especially useful:
1085   suppose you are using a package of strings which has left the type of
1086   characters in the string unspecified::
1087
1088         signature Str where
1089             data Str
1090             data Elem
1091             head :: Str -> Elem
1092
1093   If you locally define a signature which specifies
1094   ``type Elem = Char``, you can now use ``head`` from the
1095   inherited signature as if it returned a ``Char``.
1096
1097   If you do not write out the constructors, you may need to give a kind to tell
1098   GHC what the kinds of the type variables are, if they are not the default
1099   ``*``.  Unlike regular data type declarations, the return kind of an
1100   abstract data declaration can be anything (in which case it probably
1101   will be implemented using a type synonym.)  This can be used
1102   to allow compile-time representation polymorphism (as opposed to
1103   `run-time representation polymorphism <#runtime-rep>`__),
1104   as in this example::
1105
1106         signature Number where
1107             import GHC.Types
1108             data Rep :: RuntimeRep
1109             data Number :: TYPE Rep
1110             plus :: Number -> Number -> Number
1111
1112   Roles of type parameters are subject to the subtyping
1113   relation ``phantom < representational < nominal``: for example,
1114   an abstract type with a nominal type parameter can be implemented
1115   using a concrete type with a representational type parameter.
1116   Merging respects this subtyping relation (e.g., ``nominal``
1117   merged with ``representational`` is ``representational``.)
1118   Roles in signatures default to ``nominal``, which gives maximum
1119   flexibility on the implementor's side.  You should only need to
1120   give an explicit role annotation if a client of the signature
1121   would like to coerce the abstract type in a type parameter (in which case you
1122   should specify ``representational`` explicitly.)  Unlike
1123   regular data types, we do *not* assume that abstract
1124   data types are representationally injective: if we have
1125   ``Coercible (T a) (T b)``, and ``T`` has role ``nominal``,
1126   this does not imply that ``a ~ b``.
1127
1128 - A class declarations can either be abstract or concrete.  An
1129   abstract class is one with no superclasses or class methods::
1130
1131     signature A where
1132         class Key k
1133
1134   It can be implemented in any way, with any set of superclasses
1135   and methods; however, modules depending on an abstract class
1136   are not permitted to define instances (as of GHC 8.2, this
1137   restriction is not checked, see :ghc-ticket:`13086`.)
1138   These declarations can be implemented by type synonyms
1139   of kind ``Constraint``; this can be useful if you want to parametrize
1140   over a constraint in functions.  For example, with the
1141   ``ConstraintKinds`` extension, this type synonym is a valid
1142   implementation of the signature above::
1143
1144     module A where
1145         type Key = Eq
1146
1147   A concrete class specifies its superclasses, methods,
1148   default method signatures (but not their implementations)
1149   and a ``MINIMAL`` pragma.  Unlike regular Haskell classes,
1150   you don't have to explicitly declare a default for a method
1151   to make it optional vis-a-vis the ``MINIMAL`` pragma.
1152
1153   When merging class declarations, we require that the superclasses
1154   and methods match exactly; however, ``MINIMAL`` pragmas are logically
1155   ORed together, and a method with a default signature will merge
1156   successfully against one that does not.
1157
1158 - You can include instance declarations as in Haskell; just omit the
1159   "where" part.  An instance declaration need not be implemented directly;
1160   if an instance can be derived based on instances in the environment,
1161   it is considered implemented.  For example, the following signature::
1162
1163     signature A where
1164         data Str
1165         instance Eq Str
1166
1167   is considered implemented by the following module, since there
1168   are instances of ``Eq`` for ``[]`` and ``Char`` which can be combined
1169   to form an instance ``Eq [Char]``::
1170
1171     module A where
1172         type Str = [Char]
1173
1174   Unlike other declarations, for which only the entities declared
1175   in a signature file are brought into scope, instances from the
1176   implementation are always brought into scope, even if they were
1177   not declared in the signature file.  This means that a module may
1178   typecheck against a signature, but not against a matching
1179   implementation.  You can avoid situations like this by never
1180   defining orphan instances inside a package that has signatures.
1181
1182   Instance declarations are only merged if their heads are exactly
1183   the same, so it is possible to get into a situation where GHC
1184   thinks that instances in a signature are overlapping, even if
1185   they are implemented in a non-overlapping way.  If this is
1186   giving you problems give us a shout.
1187
1188 - Any orphan instances which are brought into scope by an import
1189   from a signature are unconditionally considered in scope, even
1190   if the eventual implementing module doesn't actually import the
1191   same orphans.
1192
1193 Known limitations:
1194
1195 - Pattern synonyms are not supported.
1196
1197 - Algebraic data types specified in a signature cannot be implemented using
1198   pattern synonyms.  See :ghc-ticket:`12717`
1199
1200 .. _using-make:
1201
1202 Using ``make``
1203 --------------
1204
1205 .. index::
1206    single: make; building programs with
1207
1208 It is reasonably straightforward to set up a ``Makefile`` to use with
1209 GHC, assuming you name your source files the same as your modules. Thus:
1210
1211 .. code-block:: makefile
1212
1213     HC      = ghc
1214     HC_OPTS = -cpp $(EXTRA_HC_OPTS)
1215
1216     SRCS = Main.lhs Foo.lhs Bar.lhs
1217     OBJS = Main.o   Foo.o   Bar.o
1218
1219     .SUFFIXES : .o .hs .hi .lhs .hc .s
1220
1221     cool_pgm : $(OBJS)
1222             rm -f $@
1223             $(HC) -o $@ $(HC_OPTS) $(OBJS)
1224
1225     # Standard suffix rules
1226     .o.hi:
1227             @:
1228
1229     .lhs.o:
1230             $(HC) -c $< $(HC_OPTS)
1231
1232     .hs.o:
1233             $(HC) -c $< $(HC_OPTS)
1234
1235     .o-boot.hi-boot:
1236             @:
1237
1238     .lhs-boot.o-boot:
1239             $(HC) -c $< $(HC_OPTS)
1240
1241     .hs-boot.o-boot:
1242             $(HC) -c $< $(HC_OPTS)
1243
1244     # Inter-module dependencies
1245     Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
1246     Main.o Main.hc Main.s : Foo.hi Baz.hi   # Main imports Foo and Baz
1247
1248 .. note::
1249     Sophisticated :command:`make` variants may achieve some of the above more
1250     elegantly. Notably, :command:`gmake`\'s pattern rules let you write the more
1251     comprehensible:
1252
1253     .. code-block:: make
1254
1255         %.o : %.lhs
1256                 $(HC) -c $< $(HC_OPTS)
1257
1258     What we've shown should work with any ``make``.
1259
1260 Note the cheesy ``.o.hi`` rule: It records the dependency of the
1261 interface (``.hi``) file on the source. The rule says a ``.hi`` file can
1262 be made from a ``.o`` file by doing…nothing. Which is true.
1263
1264 Note that the suffix rules are all repeated twice, once for normal
1265 Haskell source files, and once for ``hs-boot`` files (see
1266 :ref:`mutual-recursion`).
1267
1268 Note also the inter-module dependencies at the end of the Makefile,
1269 which take the form
1270
1271 .. code-block:: make
1272
1273     Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
1274
1275 They tell ``make`` that if any of ``Foo.o``, ``Foo.hc`` or ``Foo.s``
1276 have an earlier modification date than ``Baz.hi``, then the out-of-date
1277 file must be brought up to date. To bring it up to date, ``make`` looks
1278 for a rule to do so; one of the preceding suffix rules does the job
1279 nicely. These dependencies can be generated automatically by ``ghc``;
1280 see :ref:`makefile-dependencies`
1281
1282 .. _makefile-dependencies:
1283
1284 Dependency generation
1285 ---------------------
1286
1287 .. index::
1288    single: dependencies in Makefiles
1289    single: Makefile dependencies
1290
1291 Putting inter-dependencies of the form ``Foo.o : Bar.hi`` into your
1292 ``Makefile`` by hand is rather error-prone. Don't worry, GHC has support
1293 for automatically generating the required dependencies. Add the
1294 following to your ``Makefile``:
1295
1296 .. code-block:: make
1297
1298     depend :
1299             ghc -dep-suffix '' -M $(HC_OPTS) $(SRCS)
1300
1301 Now, before you start compiling, and any time you change the ``imports``
1302 in your program, do ``make depend`` before you do ``make cool_pgm``. The command
1303 ``ghc -M`` will append the needed dependencies to your ``Makefile``.
1304
1305 In general, ``ghc -M Foo`` does the following. For each module ``M`` in
1306 the set ``Foo`` plus all its imports (transitively), it adds to the
1307 Makefile:
1308
1309 -  A line recording the dependence of the object file on the source
1310    file.
1311
1312    .. code-block:: make
1313
1314        M.o : M.hs
1315
1316    (or ``M.lhs`` if that is the filename you used).
1317
1318 -  For each import declaration ``import X`` in ``M``, a line recording
1319    the dependence of ``M`` on ``X``:
1320
1321    .. code-block:: make
1322
1323        M.o : X.hi
1324
1325 -  For each import declaration ``import {-# SOURCE #-} X`` in ``M``, a
1326    line recording the dependence of ``M`` on ``X``:
1327
1328    .. code-block:: make
1329
1330        M.o : X.hi-boot
1331
1332    (See :ref:`mutual-recursion` for details of ``hi-boot`` style
1333    interface files.)
1334
1335 If ``M`` imports multiple modules, then there will be multiple lines
1336 with ``M.o`` as the target.
1337
1338 There is no need to list all of the source files as arguments to the
1339 ``ghc -M`` command; ``ghc`` traces the dependencies, just like
1340 ``ghc --make`` (a new feature in GHC 6.4).
1341
1342 Note that ``ghc -M`` needs to find a *source file* for each module in
1343 the dependency graph, so that it can parse the import declarations and
1344 follow dependencies. Any pre-compiled modules without source files must
1345 therefore belong to a package [1]_.
1346
1347 By default, ``ghc -M`` generates all the dependencies, and then
1348 concatenates them onto the end of ``makefile`` (or ``Makefile`` if
1349 ``makefile`` doesn't exist) bracketed by the lines
1350 "``# DO NOT DELETE: Beginning of Haskell dependencies``" and
1351 "``# DO NOT DELETE: End of Haskell dependencies``". If these lines
1352 already exist in the ``makefile``, then the old dependencies are deleted
1353 first.
1354
1355 Don't forget to use the same ``-package`` options on the ``ghc -M``
1356 command line as you would when compiling; this enables the dependency
1357 generator to locate any imported modules that come from packages. The
1358 package modules won't be included in the dependencies generated, though
1359 (but see the ``-include-pkg-deps`` option below).
1360
1361 The dependency generation phase of GHC can take some additional options,
1362 which you may find useful. The options which affect dependency
1363 generation are:
1364
1365 .. ghc-flag:: -ddump-mod-cycles
1366     :shortdesc: Dump module cycles
1367     :type: dynamic
1368     :category:
1369
1370     Display a list of the cycles in the module graph. This is useful
1371     when trying to eliminate such cycles.
1372
1373 .. ghc-flag:: -v2
1374     :noindex:
1375
1376     Print a full list of the module dependencies to stdout. (This is the
1377     standard verbosity flag, so the list will also be displayed with
1378     ``-v3`` and ``-v4``; see :ref:`options-help`.)
1379
1380 .. ghc-flag:: -dep-makefile ⟨file⟩
1381     :shortdesc: Use ⟨file⟩ as the makefile
1382     :type: dynamic
1383     :category:
1384
1385     Use ⟨file⟩ as the makefile, rather than ``makefile`` or
1386     ``Makefile``. If ⟨file⟩ doesn't exist, ``mkdependHS`` creates it. We
1387     often use ``-dep-makefile .depend`` to put the dependencies in
1388     ``.depend`` and then ``include`` the file ``.depend`` into
1389     ``Makefile``.
1390
1391 .. ghc-flag:: -dep-suffix ⟨suffix⟩
1392     :shortdesc: Make dependencies that declare that files with suffix
1393         ``.⟨suf⟩⟨osuf⟩`` depend on interface files with suffix ``.⟨suf⟩hi``
1394     :type: dynamic
1395     :category:
1396
1397     Make dependencies that declare that files with suffix
1398     ``.⟨suf⟩⟨osuf⟩`` depend on interface files with suffix
1399     ``.⟨suf⟩hi``, or (for ``{-# SOURCE #-}`` imports) on ``.hi-boot``.
1400     Multiple ``-dep-suffix`` flags are permitted. For example,
1401     ``-dep-suffix a_ -dep-suffix b_`` will make dependencies for ``.hs``
1402     on ``.hi``, ``.a_hs`` on ``.a_hi``, and ``.b_hs`` on ``.b_hi``.
1403     Note that you must provide at least one suffix; if you do not want a suffix
1404     then pass ``-dep-suffix ''``.
1405
1406 .. ghc-flag:: --exclude-module=⟨file⟩
1407     :shortdesc: Regard ``⟨file⟩`` as "stable"; i.e., exclude it from having
1408         dependencies on it.
1409     :type: dynamic
1410     :category:
1411
1412     Regard ``⟨file⟩`` as "stable"; i.e., exclude it from having
1413     dependencies on it.
1414
1415 .. ghc-flag:: -include-pkg-deps
1416     :shortdesc: Regard modules imported from packages as unstable
1417     :type: dynamic
1418     :category:
1419
1420     Regard modules imported from packages as unstable, i.e., generate
1421     dependencies on any imported package modules (including ``Prelude``,
1422     and all other standard Haskell libraries). Dependencies are not
1423     traced recursively into packages; dependencies are only generated
1424     for home-package modules on external-package modules directly
1425     imported by the home package module. This option is normally only
1426     used by the various system libraries.
1427
1428 .. ghc-flag:: -include-cpp-deps
1429     :shortdesc: Include preprocessor dependencies
1430     :type: dynamic
1431     :category:
1432
1433     Output preprocessor dependencies. This only has an effect when the CPP
1434     language extension is enabled. These dependencies are files included with
1435     the ``#include`` preprocessor directive (as well as transitive includes) and
1436     implicitly included files such as standard c preprocessor headers and a GHC
1437     version header. One exception to this is that GHC generates a temporary
1438     header file (during compilation) containing package version macros. As this
1439     is only a temporary file that GHC will always generate, it is not output as
1440     a dependency.
1441
1442 .. _orphan-modules:
1443
1444 Orphan modules and instance declarations
1445 ----------------------------------------
1446
1447 Haskell specifies that when compiling module ``M``, any instance declaration
1448 in any module "below" ``M`` is visible. (Module ``A`` is "below" ``M`` if ``A`` is
1449 imported directly by ``M``, or if ``A`` is below a module that ``M`` imports
1450 directly.) In principle, GHC must therefore read the interface files of
1451 every module below ``M``, just in case they contain an instance declaration
1452 that matters to ``M``. This would be a disaster in practice, so GHC tries to
1453 be clever.
1454
1455 In particular, if an instance declaration is in the same module as the
1456 definition of any type or class mentioned in the *head* of the instance
1457 declaration (the part after the "``=>``"; see :ref:`instance-rules`), then GHC
1458 has to visit that interface file anyway. Example: ::
1459
1460       module A where
1461         instance C a => D (T a) where ...
1462         data T a = ...
1463
1464 The instance declaration is only relevant if the type ``T`` is in use, and
1465 if so, GHC will have visited ``A``\'s interface file to find ``T``\'s definition.
1466
1467 The only problem comes when a module contains an instance declaration
1468 and GHC has no other reason for visiting the module. Example: ::
1469
1470       module Orphan where
1471         instance C a => D (T a) where ...
1472         class C a where ...
1473
1474 Here, neither ``D`` nor ``T`` is declared in module ``Orphan``. We call such modules
1475 "orphan modules". GHC identifies orphan modules, and visits the
1476 interface file of every orphan module below the module being compiled.
1477 This is usually wasted work, but there is no avoiding it. You should
1478 therefore do your best to have as few orphan modules as possible.
1479
1480 Functional dependencies complicate matters. Suppose we have: ::
1481
1482       module B where
1483         instance E T Int where ...
1484         data T = ...
1485
1486 Is this an orphan module? Apparently not, because ``T`` is declared in
1487 the same module. But suppose class ``E`` had a functional dependency: ::
1488
1489       module Lib where
1490         class E x y | y -> x where ...
1491
1492 Then in some importing module ``M``, the constraint ``(E a Int)`` should be
1493 "improved" by setting ``a = T``, *even though there is no explicit
1494 mention* of ``T`` in ``M``.
1495
1496 These considerations lead to the following definition of an orphan
1497 module:
1498
1499 -  An *orphan module* orphan module contains at least one *orphan
1500    instance* or at least one *orphan rule*.
1501
1502 -  An instance declaration in a module ``M`` is an *orphan instance* if
1503    orphan instance
1504
1505    -  The class of the instance declaration is not declared in ``M``, and
1506
1507    -  *Either* the class has no functional dependencies, and none of the
1508       type constructors in the instance head is declared in ``M``; *or*
1509       there is a functional dependency for which none of the type
1510       constructors mentioned in the *non-determined* part of the
1511       instance head is defined in ``M``.
1512
1513    Only the instance head counts. In the example above, it is not good
1514    enough for ``C``\'s declaration to be in module ``A``; it must be the
1515    declaration of ``D`` or ``T``.
1516
1517 -  A rewrite rule in a module ``M`` is an *orphan rule* orphan rule if none
1518    of the variables, type constructors, or classes that are free in the
1519    left hand side of the rule are declared in ``M``.
1520
1521 If you use the flag :ghc-flag:`-Worphans`, GHC will warn you if you are
1522 creating an orphan module. Like any warning, you can switch the warning
1523 off with :ghc-flag:`-Wno-orphans <-Worphans>`, and :ghc-flag:`-Werror` will make
1524 the compilation fail if the warning is issued.
1525
1526 You can identify an orphan module by looking in its interface file, ``M.hi``,
1527 using the :ghc-flag:`--show-iface ⟨file⟩` :ref:`mode <modes>`. If there is a
1528 ``[orphan module]`` on the first line, GHC considers it an orphan module.
1529
1530 .. [1]
1531    This is a change in behaviour relative to 6.2 and earlier.