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