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