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