-</Sect2>
-
-</Sect1>
-
-<Sect1 id="options-sanity">
-<Title>Warnings and sanity-checking
-</Title>
-
-<Para>
-<IndexTerm><Primary>sanity-checking options</Primary></IndexTerm>
-<IndexTerm><Primary>warnings</Primary></IndexTerm>
-GHC has a number of options that select which types of non-fatal error
-messages, otherwise known as warnings, can be generated during
-compilation. By default, you get a standard set of warnings which are
-generally likely to indicate bugs in your program. These are:
-<Option>-fwarn-overlpapping-patterns</Option>, <Option>-fwarn-duplicate-exports</Option>, and
-<Option>-fwarn-missing-methods</Option>. The following flags are simple ways to
-select standard “packages” of warnings:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Option>-Wnot</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-Wnot option</Primary></IndexTerm>
-Turns off all warnings, including the standard ones.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-w</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-w option</Primary></IndexTerm>
-Synonym for <Option>-Wnot</Option>.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-W</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-W option</Primary></IndexTerm>
-Provides the standard warnings plus <Option>-fwarn-incomplete-patterns</Option>,
-<Option>-fwarn-unused-imports</Option> and <Option>-fwarn-unused-binds</Option>.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-Wall</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-Wall option</Primary></IndexTerm>
-Turns on all warning options.
-</Para>
-</ListItem>
-</VarListEntry>
-
-</VariableList>
-</Para>
-
-<Para>
-The full set of warning options is described below. To turn off any
-warning, simply give the corresponding <Option>-fno-warn-...</Option> option on
-the command line.
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Option>-fwarn-name-shadowing</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-name-shadowing option</Primary></IndexTerm>
-<IndexTerm><Primary>shadowing, warning</Primary></IndexTerm>This option causes a warning to be emitted whenever an inner-scope
-value has the same name as an outer-scope value, i.e. the inner value
-shadows the outer one. This can catch typographical errors that turn
-into hard-to-find bugs, e.g., in the inadvertent cyclic definition
-<Literal>let x = ... x ... in</Literal>.
-</Para>
-
-<Para>
-Consequently, this option does <Emphasis>not</Emphasis> allow cyclic recursive
-definitions.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-fwarn-overlapping-patterns</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-overlapping-patterns option</Primary></IndexTerm>
-<IndexTerm><Primary>overlapping patterns, warning</Primary></IndexTerm>
-<IndexTerm><Primary>patterns, overlapping</Primary></IndexTerm>
-By default, the compiler will warn you if a set of patterns are
-overlapping, i.e.,
-</Para>
-
-<Para>
-<ProgramListing>
-f :: String -> Int
-f [] = 0
-f (_:xs) = 1
-f "2" = 2
-</ProgramListing>
-</Para>
-
-<Para>
-where the last pattern match in <Function>f</Function> won't ever be reached, as the
-second pattern overlaps it. More often than not, redundant patterns
-is a programmer mistake/error, so this option is enabled by default.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-fwarn-incomplete-patterns</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-incomplete-patterns option</Primary></IndexTerm>
-<IndexTerm><Primary>incomplete patterns, warning</Primary></IndexTerm>
-<IndexTerm><Primary>patterns, incomplete</Primary></IndexTerm>
-Similarly for incomplete patterns, the function <Function>g</Function> below will fail
-when applied to non-empty lists, so the compiler will emit a warning
-about this when <Option>-fwarn-incomplete-patterns</Option> is enabled.
-</Para>
-
-<Para>
-<ProgramListing>
-g [] = 2
-</ProgramListing>
-</Para>
-
-<Para>
-This option isn't enabled be default because it can be a bit noisy,
-and it doesn't always indicate a bug in the program. However, it's
-generally considered good practice to cover all the cases in your
-functions.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-fwarn-missing-methods</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-missing-methods option</Primary></IndexTerm>
-<IndexTerm><Primary>missing methods, warning</Primary></IndexTerm>
-<IndexTerm><Primary>methods, missing</Primary></IndexTerm>
-This option is on by default, and warns you whenever an instance
-declaration is missing one or more methods, and the corresponding
-class declaration has no default declaration for them.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-fwarn-missing-fields</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-missing-fields option</Primary></IndexTerm>
-<IndexTerm><Primary>missing fields, warning</Primary></IndexTerm>
-<IndexTerm><Primary>fields, missing</Primary></IndexTerm>
-This option is on by default, and warns you whenever the construction
-of a labelled field constructor isn't complete, missing initializers
-for one or more fields. While not an error (the missing fields are
-initialised with bottoms), it is often an indication of a programmer
-error.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-fwarn-unused-imports</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-unused-imports option</Primary></IndexTerm>
-<IndexTerm><Primary>unused imports, warning</Primary></IndexTerm>
-<IndexTerm><Primary>imports, unused</Primary></IndexTerm>
-Report any objects that are explicitly imported but never used.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-fwarn-unused-binds</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-unused-binds option</Primary></IndexTerm>
-<IndexTerm><Primary>unused binds, warning</Primary></IndexTerm>
-<IndexTerm><Primary>binds, unused</Primary></IndexTerm>
-Report any function definitions (and local bindings) which are unused.
-For top-level functions, the warning is only given if the binding is
-not exported.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-fwarn-unused-matches</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-unused-matches option</Primary></IndexTerm>
-<IndexTerm><Primary>unused matches, warning</Primary></IndexTerm>
-<IndexTerm><Primary>matches, unused</Primary></IndexTerm>
-Report all unused variables which arise from pattern matches,
-including patterns consisting of a single variable. For instance <Literal>f x
-y = []</Literal> would report <VarName>x</VarName> and <VarName>y</VarName> as unused. To eliminate the warning,
-all unused variables can be replaced with wildcards.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-fwarn-duplicate-exports</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-duplicate-exports option</Primary></IndexTerm>
-<IndexTerm><Primary>duplicate exports, warning</Primary></IndexTerm>
-<IndexTerm><Primary>export lists, duplicates</Primary></IndexTerm>
-Have the compiler warn about duplicate entries in export lists. This
-is useful information if you maintain large export lists, and want to
-avoid the continued export of a definition after you've deleted (one)
-mention of it in the export list.
-</Para>
-
-<Para>
-This option is on by default.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-fwarn-type-defaults</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-type-defaults option</Primary></IndexTerm>
-<IndexTerm><Primary>defaulting mechanism, warning</Primary></IndexTerm>
-Have the compiler warn/inform you where in your source the Haskell
-defaulting mechanism for numeric types kicks in. This is useful
-information when converting code from a context that assumed one
-default into one with another, e.g., the `default default' for Haskell
-1.4 caused the otherwise unconstrained value <Constant>1</Constant> to be given
-the type <Literal>Int</Literal>, whereas Haskell 98 defaults it to
-<Literal>Integer</Literal>. This may lead to differences in performance and
-behaviour, hence the usefulness of being non-silent about this.
-</Para>
-
-<Para>
-This warning is off by default.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-fwarn-missing-signatures</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-missing-signatures option</Primary></IndexTerm>
-<IndexTerm><Primary>type signatures, missing</Primary></IndexTerm>
-If you would like GHC to check that every top-level function/value has
-a type signature, use the <Option>-fwarn-missing-signatures</Option> option. This
-option is off by default.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-If you're feeling really paranoid, the <Option>-dcore-lint</Option>
-option<IndexTerm><Primary>-dcore-lint option</Primary></IndexTerm> is a good choice. It turns on
-heavyweight intra-pass sanity-checking within GHC. (It checks GHC's
-sanity, not yours.)
-</Para>
-
-</Sect1>
-
-<Sect1 id="separate-compilation">
-<Title>Separate compilation
-</Title>
-
-<Para>
-<IndexTerm><Primary>separate compilation</Primary></IndexTerm>
-<IndexTerm><Primary>recompilation checker</Primary></IndexTerm>
-<IndexTerm><Primary>make and recompilation</Primary></IndexTerm>
-This section describes how GHC supports separate compilation.
-</Para>
-
-<Sect2 id="hi-files">
-<Title>Interface files
-</Title>
-
-<Para>
-<IndexTerm><Primary>interface files</Primary></IndexTerm>
-<IndexTerm><Primary>.hi files</Primary></IndexTerm>
-</Para>
-
-<Para>
-When GHC compiles a source file <Filename>F</Filename> which contains a module <Literal>A</Literal>, say,
-it generates an object <Filename>F.o</Filename>, <Emphasis>and</Emphasis> a companion <Emphasis>interface
-file</Emphasis> <Filename>A.hi</Filename>. The interface file is not intended for human
-consumption, as you'll see if you take a look at one. It's merely
-there to help the compiler compile other modules in the same program.
-</Para>
-
-<Para>
-NOTE: Having the name of the interface file follow the module name and
-not the file name, means that working with tools such as <Command>make</Command>
-become harder. <Command>make</Command> implicitly assumes that any output files
-produced by processing a translation unit will have file names that
-can be derived from the file name of the translation unit. For
-instance, pattern rules becomes unusable. For this reason, we
-recommend you stick to using the same file name as the module name.
-</Para>
-
-<Para>
-The interface file for <Literal>A</Literal> contains information needed by the compiler
-when it compiles any module <Literal>B</Literal> that imports <Literal>A</Literal>, whether directly or
-indirectly. When compiling <Literal>B</Literal>, GHC will read <Filename>A.hi</Filename> to find the
-details that it needs to know about things defined in <Literal>A</Literal>.
-</Para>
-
-<Para>
-Furthermore, when compiling module <Literal>C</Literal> which imports <Literal>B</Literal>, GHC may
-decide that it needs to know something about <Literal>A</Literal>—for example, <Literal>B</Literal>
-might export a function that involves a type defined in <Literal>A</Literal>. In this
-case, GHC will go and read <Command>A.hi</Command> even though <Literal>C</Literal> does not explicitly
-import <Literal>A</Literal> at all.
-</Para>
-
-<Para>
-The interface file may contain all sorts of things that aren't
-explicitly exported from <Literal>A</Literal> by the programmer. For example, even
-though a data type is exported abstractly, <Filename>A.hi</Filename> will contain the
-full data type definition. For small function definitions, <Filename>A.hi</Filename>
-will contain the complete definition of the function. For bigger
-functions, <Filename>A.hi</Filename> will contain strictness information about the
-function. And so on. GHC puts much more information into <Filename>.hi</Filename> files
-when optimisation is turned on with the <Option>-O</Option> flag. Without <Option>-O</Option> it
-puts in just the minimum; with <Option>-O</Option> it lobs in a whole pile of stuff.
-<IndexTerm><Primary>optimsation, effect on .hi files</Primary></IndexTerm>
-</Para>
-
-<Para>
-<Filename>A.hi</Filename> should really be thought of as a compiler-readable version of
-<Filename>A.o</Filename>. If you use a <Filename>.hi</Filename> file that wasn't generated by the same
-compilation run that generates the <Filename>.o</Filename> file the compiler may assume
-all sorts of incorrect things about <Literal>A</Literal>, resulting in core dumps and
-other unpleasant happenings.
-</Para>
-
-</Sect2>
-
-<Sect2 id="options-finding-imports">
-<Title>Finding interface files
-</Title>
-
-<Para>
-<IndexTerm><Primary>interface files, finding them</Primary></IndexTerm>
-<IndexTerm><Primary>finding interface files</Primary></IndexTerm>
-</Para>
-
-<Para>
-In your program, you import a module <Literal>Foo</Literal> by saying
-<Literal>import Foo</Literal>. GHC goes looking for an interface file, <Filename>Foo.hi</Filename>.
-It has a builtin list of directories (notably including <Filename>.</Filename>) where
-it looks.
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Option>-i<dirs></Option></Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-i<dirs> option</Primary></IndexTerm>This flag
-prepends a colon-separated list of <Filename>dirs</Filename> to the “import
-directories” list.
-See also <XRef LinkEnd="recomp"> for the significance of using
-relative and absolute pathnames in the <Option>-i</Option> list.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-i</Option></Term>
-<ListItem>
-<Para>
-resets the “import directories” list back to nothing.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-fno-implicit-prelude</Option></Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fno-implicit-prelude option</Primary></IndexTerm>
-GHC normally imports <Filename>Prelude.hi</Filename> files for you. If you'd rather it
-didn't, then give it a <Option>-fno-implicit-prelude</Option> option. You are
-unlikely to get very far without a Prelude, but, hey, it's a free
-country.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-I<dir></Option></Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-I<dir> option</Primary></IndexTerm>
-Once a Haskell module has been compiled to C (<Filename>.hc</Filename> file), you may
-wish to specify where GHC tells the C compiler to look for <Filename>.h</Filename> files.
-(Or, if you are using the <Option>-cpp</Option> option<IndexTerm><Primary>-cpp option</Primary></IndexTerm>, where
-it tells the C pre-processor to look…) For this purpose, use a <Option>-I</Option>
-option in the usual C-ish way.
-</Para>
-</ListItem>
-</VarListEntry>
-
-</VariableList>
-</Para>
-
-</Sect2>
-
-<Sect2 id="hi-options">
-<Title>Other options related to interface files
-</Title>
-
-<Para>
-<IndexTerm><Primary>interface files, options</Primary></IndexTerm>
-The interface output may be directed to another file
-<Filename>bar2/Wurble.iface</Filename> with the option <Option>-ohi bar2/Wurble.iface</Option><IndexTerm><Primary>-ohi
-<file> option</Primary></IndexTerm> (not recommended).
-</Para>
-
-<Para>
-To avoid generating an interface file at all, use a <Option>-nohi</Option>
-option.<IndexTerm><Primary>-nohi option</Primary></IndexTerm>
-</Para>
-
-<Para>
-The compiler does not overwrite an existing <Filename>.hi</Filename> interface file if
-the new one is byte-for-byte the same as the old one; this is friendly
-to <Command>make</Command>. When an interface does change, it is often enlightening to
-be informed. The <Option>-hi-diffs</Option><IndexTerm><Primary>-hi-diffs option</Primary></IndexTerm> option will
-make GHC run <Command>diff</Command> on the old and new <Filename>.hi</Filename> files. You can also
-record the difference in the interface file itself, the
-<Option>-keep-hi-diffs</Option><IndexTerm><Primary>-keep-hi-diffs</Primary></IndexTerm> option takes care of that.
-</Para>
-
-<Para>
-The <Filename>.hi</Filename> files from GHC contain “usage” information which changes
-often and uninterestingly. If you really want to see these changes
-reported, you need to use the
-<Option>-hi-diffs-with-usages</Option><IndexTerm><Primary>-hi-diffs-with-usages option</Primary></IndexTerm>
-option.
-</Para>
-
-<Para>
-Interface files are normally jammed full of compiler-produced
-<Emphasis>pragmas</Emphasis>, which record arities, strictness info, etc. If you
-think these pragmas are messing you up (or you are doing some kind of
-weird experiment), you can tell GHC to ignore them with the
-<Option>-fignore-interface-pragmas</Option><IndexTerm><Primary>-fignore-interface-pragmas
-option</Primary></IndexTerm> option.
-</Para>
-
-<Para>
-When compiling without optimisations on, the compiler is extra-careful
-about not slurping in data constructors and instance declarations that
-it will not need. If you believe it is getting it wrong and not
-importing stuff which you think it should, this optimisation can be
-turned off with <Option>-fno-prune-tydecls</Option> and <Option>-fno-prune-instdecls</Option>.
-<IndexTerm><Primary>-fno-prune-tydecls option</Primary></IndexTerm><IndexTerm><Primary>-fno-prune-instdecls
-option</Primary></IndexTerm>
-</Para>
-
-<Para>
-See also <XRef LinkEnd="options-linker">, which describes how the linker finds standard
-Haskell libraries.
-</Para>
-
-</Sect2>
-
-<Sect2 id="recomp">
-<Title>The recompilation checker
-</Title>
-
-<IndexTerm><Primary>recompilation checker</Primary></IndexTerm>
-
-<Para>
-<variablelist>
-<VarListEntry>
-<Term><Option>-recomp</Option></Term>
-<IndexTerm><Primary><option>-recomp</option> option</Primary></IndexTerm>
-<ListItem>
-<Para>
-(On by default) Turn on recompilation checking. This will stop
-compilation early, leaving an existing <filename>.o</filename> file in
-place, if it can be determined that the module does not need to be
-recompiled.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-no-recomp</Option></Term>
-<IndexTerm><Primary><option>-recomp</option> option</Primary></IndexTerm>
-<ListItem>
-<Para>
-Turn off recompilation checking.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-In the olden days, GHC compared the newly-generated
-<Filename>.hi</Filename> file with the previous version; if they were
-identical, it left the old one alone and didn't change its
-modification date. In consequence, importers of a module with an
-unchanged output <Filename>.hi</Filename> file were not recompiled.
-</Para>
-
-<Para>
-This doesn't work any more. In our earlier example, module
-<Literal>C</Literal> does not import module <Literal>A</Literal>
-directly, yet changes to <Filename>A.hi</Filename> should force a
-recompilation of <Literal>C</Literal>. And some changes to
-<Literal>A</Literal> (changing the definition of a function that
-appears in an inlining of a function exported by <Literal>B</Literal>,
-say) may conceivably not change <Filename>B.hi</Filename> one jot. So
-now…
-</Para>
-
-<Para>
-GHC keeps a version number on each interface file, and on each type
-signature within the interface file. It also keeps in every interface
-file a list of the version numbers of everything it used when it last
-compiled the file. If the source file's modification date is earlier
-than the <Filename>.o</Filename> file's date (i.e. the source hasn't
-changed since the file was last compiled), and the
-<option>-recomp</option> is given on the command line, GHC will be
-clever. It compares the version numbers on the things it needs this
-time with the version numbers on the things it needed last time
-(gleaned from the interface file of the module being compiled); if
-they are all the same it stops compiling rather early in the process
-saying “Compilation IS NOT required”. What a beautiful
-sight!
-</Para>
-
-<Para>
-Patrick Sansom had a workshop paper about how all this is done (though
-the details have changed quite a bit). <ULink URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a copy.
-</Para>
-
-</Sect2>
-
-
-<Sect2 id="using-make">
-<Title>Using <Command>make</Command>
-</Title>
-
-<Para>
-<IndexTerm><Primary><literal>make</literal></Primary></IndexTerm>
-</Para>
-
-<Para>
-It is reasonably straightforward to set up a <Filename>Makefile</Filename> to use with GHC, assuming you name your source files the same as your modules.
-Thus:
-</Para>
-
-<Para>
-
-<ProgramListing>
-HC = ghc
-HC_OPTS = -cpp $(EXTRA_HC_OPTS)
-
-SRCS = Main.lhs Foo.lhs Bar.lhs
-OBJS = Main.o Foo.o Bar.o
-
-.SUFFIXES : .o .hs .hi .lhs .hc .s
-
-cool_pgm : $(OBJS)
- rm $@
- $(HC) -o $@ $(HC_OPTS) $(OBJS)
-
-# Standard suffix rules
-.o.hi:
- @:
-
-.lhs.o:
- $(HC) -c $< $(HC_OPTS)
-
-.hs.o:
- $(HC) -c $< $(HC_OPTS)
-
-# Inter-module dependencies
-Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
-Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz
-</ProgramListing>
-
-</Para>
-
-<Para>
-(Sophisticated <Command>make</Command> variants may achieve some of the above more
-elegantly. Notably, <Command>gmake</Command>'s pattern rules let you write the more
-comprehensible:
-</Para>
-
-<Para>
-
-<ProgramListing>
-%.o : %.lhs
- $(HC) -c $< $(HC_OPTS)
-</ProgramListing>
-
-</Para>
-
-<Para>
-What we've shown should work with any <Command>make</Command>.)
-</Para>
-
-<Para>
-Note the cheesy <Literal>.o.hi</Literal> rule: It records the dependency of the
-interface (<Filename>.hi</Filename>) file on the source. The rule says a <Filename>.hi</Filename> file can
-be made from a <Filename>.o</Filename> file by doing…nothing. Which is true.
-</Para>
-
-<Para>
-Note the inter-module dependencies at the end of the Makefile, which
-take the form
-</Para>
-
-<Para>
-
-<ProgramListing>
-Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
-</ProgramListing>
-
-</Para>
-
-<Para>
-They tell <Command>make</Command> that if any of <Literal>Foo.o</Literal>, <Literal>Foo.hc</Literal> or <Literal>Foo.s</Literal> have an
-earlier modification date than <Literal>Baz.hi</Literal>, then the out-of-date file
-must be brought up to date. To bring it up to date, <Literal>make</Literal> looks for
-a rule to do so; one of the preceding suffix rules does the job
-nicely.
-</Para>
-
- </sect2>
-
- <sect2 id="sec-makefile-dependencies">
- <title>Dependency generation</title>
- <indexterm><primary>dependencies in Makefiles</primary></indexterm>
- <indexterm><primary>Makefile dependencies</primary></indexterm>
-
- <para>Putting inter-dependencies of the form <Literal>Foo.o :
- Bar.hi</Literal> into your <Filename>Makefile</Filename> by hand
- is rather error-prone. Don't worry, GHC has support for
- automatically generating the required dependencies. Add the
- following to your <Filename>Makefile</Filename>:</para>
-
-<ProgramListing>
-depend :
- ghc -M $(HC_OPTS) $(SRCS)
-</ProgramListing>
-
- <para>Now, before you start compiling, and any time you change
- the <Literal>imports</Literal> in your program, do <Command>make
- depend</Command> before you do <Command>make
- cool_pgm</Command>. <Command>ghc -M</Command> will append
- the needed dependencies to your
- <Filename>Makefile</Filename>.</Para>
-
- <para>In general, if module <Literal>A</Literal> contains the
- line
-
-<programlisting>
-import B ...blah...
-</programlisting>
-
- then <command>ghc -M</command> will generate a dependency
- line of the form:
-
-<programlisting>
-A.o : B.hi
-</programlisting>
-
- If module <literal>A</literal> contains the line
-
-<programlisting>
-import {-# SOURCE #-} B ...blah...
-</programlisting>
-
- then <command>ghc -M</command> will generate a dependency
- line of the form:
-
-<programlisting>
-A.o : B.hi-boot
-</programlisting>
-
- (See <xref linkend="hi-files"> for details of interface files.)
- If <literal>A</literal> imports multiple modules, then there
- will be multiple lines with <filename>A.o</filename> as the
- target.</para>
-
- <para>By default, <Command>ghc -M</Command> generates all the
- dependencies, and then concatenates them onto the end of
- <Filename>makefile</Filename> (or <Filename>Makefile</Filename>
- if <Filename>makefile</Filename> doesn't exist) bracketed by the
- lines "<Literal># DO NOT DELETE: Beginning of Haskell
- dependencies</Literal>" and "<Literal># DO NOT DELETE: End
- of Haskell dependencies</Literal>". If these lines already
- exist in the <Filename>makefile</Filename>, then the old
- dependencies are deleted first.</para>
-
- <para>Internally, GHC uses a script to generate the
- dependencies, called <command>mkdependHS</command>. This script
- has some options of its own, which you might find useful.
- Options can be passed directly to <command>mkdependHS</command>
- with GHC's <literal>-optdep</literal> option. For example, to
- generate the dependencies into a file called
- <literal>.depend</literal> instead of
- <literal>Makefile</literal>:</para>
-
-<screen>
-ghc -M -optdep-f optdep.depend ...
-</screen>
-
- <para>The full list of options accepted by
- <command>mkdependHS</command> is:</para>
-
- <variablelist>
-
- <varlistentry>
- <term><option>-w</option></term>
- <listitem>
- <para>Turn off warnings about interface file shadowing.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-f blah</option></term>
- <listitem>
- <para>Use <Filename>blah</Filename> as the makefile,
- rather than <Filename>makefile</Filename> or
- <Filename>Makefile</Filename>. If
- <Filename>blah</Filename> doesn't exist,
- <Command>mkdependHS</Command> creates it. We often use
- <Option>-f .depend</Option> to put the dependencies in
- <Filename>.depend</Filename> and then
- <Command>include</Command> the file
- <Filename>.depend</Filename> into
- <Filename>Makefile</Filename>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-o <osuf></option></term>
- <listitem>
- <para>Use <Filename>.<osuf></Filename> as the
- "target file" suffix ( default: <Literal>o</Literal>).
- Multiple <Option>-o</Option> flags are permitted (GHC2.05
- onwards). Thus "<Option>-o hc -o o</Option>" will
- generate dependencies for <Filename>.hc</Filename> and
- <Filename>.o</Filename> files.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-s <suf></option></term>
- <listitem>
- <para>Make extra dependencies that declare that files with
- suffix
- <Filename>.<suf>_<osuf></Filename>
- depend on interface files with suffix
- <Filename>.<suf>_hi</Filename>, or (for
- <Literal>{-# SOURCE #-}</Literal>
- imports) on <Filename>.hi-boot</Filename>. Multiple
- <Option>-s</Option> flags are permitted. For example,
- <Option>-o hc -s a -s b</Option> will make dependencies
- for <Filename>.hc</Filename> on <Filename>.hi</Filename>,
- <Filename>.a_hc</Filename> on
- <Filename>.a_hi</Filename>, and
- <Filename>.b_hc</Filename> on
- <Filename>.b_hi</Filename>. (Useful in conjunction
- with NoFib "ways".)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--exclude-module=<file></option></term>
- <listitem>
- <para>Regard <Filename><file></Filename> as
- "stable"; i.e., exclude it from having dependencies on
- it.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-x</option></term>
- <listitem>
- <para>same as <option>--exclude-module</option></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--exclude-directory=<dirs></option></term>
- <listitem>
- <para>Regard the colon-separated list of directories
- <Filename><dirs></Filename> as containing stable,
- don't generate any dependencies on modules therein.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-xdirs</option></term>
- <listitem>
- <para>same as <Option>--exclude-directory</Option>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--include-module=<file></option></term>
- <listitem>
- <para>Regard <Filename><file></Filename> as not
- "stable"; i.e., generate dependencies on it (if any). This
- option is normally used in conjunction with the
- <Option>--exclude-directory</Option> option.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--include-prelude</option></term>
- <listitem>
- <para>Regard prelude libraries as unstable, i.e., generate
- dependencies on the prelude modules used (including
- <Literal>Prelude</Literal>). This option is normally only
- used by the various system libraries. If a
- <Option>-package</Option> option is used, dependencies will
- also be generated on the library's interfaces.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
-</Sect2>
-
-<Sect2 id="mutual-recursion">
-<Title>How to compile mutually recursive modules
-</Title>
-
-<Para>
-<IndexTerm><Primary>module system, recursion</Primary></IndexTerm>
-<IndexTerm><Primary>recursion, between modules</Primary></IndexTerm>
-</Para>
-
-<Para>
-Currently, the compiler does not have proper support for dealing with
-mutually recursive modules:
-</Para>
-
-<Para>
-
-<ProgramListing>
-module A where
-
-import B
-
-newtype TA = MkTA Int
-
-f :: TB -> TA
-f (MkTB x) = MkTA x
---------
-module B where
-
-import A
-
-data TB = MkTB !Int
-
-g :: TA -> TB
-g (MkTA x) = MkTB x
-</ProgramListing>
-
-</Para>
-
-<Para>
-When compiling either module A and B, the compiler will try (in vain)
-to look for the interface file of the other. So, to get mutually
-recursive modules off the ground, you need to hand write an interface
-file for A or B, so as to break the loop. These hand-written
-interface files are called <Literal>hi-boot</Literal> files, and are placed in a file
-called <Filename><module>.hi-boot</Filename>. To import from an <Literal>hi-boot</Literal> file instead
-of the standard <Filename>.hi</Filename> file, use the following syntax in the importing module:
-<IndexTerm><Primary>hi-boot files</Primary></IndexTerm>
-<IndexTerm><Primary>importing, hi-boot files</Primary></IndexTerm>
-</Para>
-
-<Para>
-
-<ProgramListing>
-import {-# SOURCE #-} A
-</ProgramListing>
-
-</Para>
-
-<Para>
-The hand-written interface need only contain the bare minimum of
-information needed to get the bootstrapping process started. For
-example, it doesn't need to contain declarations for <Emphasis>everything</Emphasis>
-that module <Literal>A</Literal> exports, only the things required by the module that
-imports <Literal>A</Literal> recursively.
-</Para>
-
-<Para>
-For the example at hand, the boot interface file for A would look like
-the following:
-</Para>
-
-<Para>
-
-<ProgramListing>
-__interface A 1 404 where
-__export A TA{MkTA} ;
-1 newtype TA = MkTA PrelBase.Int ;
-</ProgramListing>
-
-</Para>
-
-<Para>
-The syntax is essentially the same as a normal <Filename>.hi</Filename> file
-(unfortunately), but you can usually tailor an existing <Filename>.hi</Filename> file to
-make a <Filename>.hi-boot</Filename> file.
-</Para>
-
-<Para>
-Notice that we only put the declaration for the newtype <Literal>TA</Literal> in the
-<Literal>hi-boot</Literal> file, not the signature for <Function>f</Function>, since <Function>f</Function> isn't used by
-<Literal>B</Literal>.
-</Para>
-
-<Para>
-The number “1” after “__interface A” gives the version number of module A;
-it is incremented whenever anything in A's interface file changes. The “404” is
-the version number of the interface file <Emphasis>syntax</Emphasis>; we change it when
-we change the syntax of interface files so that you get a better error message when
-you try to read an old-format file with a new-format compiler.
-</Para>
-
-<Para>
-The number “1” at the beginning of a declaration is the <Emphasis>version
-number</Emphasis> of that declaration: for the purposes of <Filename>.hi-boot</Filename> files
-these can all be set to 1. All names must be fully qualified with the
-<Emphasis>original</Emphasis> module that an object comes from: for example, the
-reference to <Literal>Int</Literal> in the interface for <Literal>A</Literal> comes from <Literal>PrelBase</Literal>,
-which is a module internal to GHC's prelude. It's a pain, but that's
-the way it is.
-</Para>
-
-<Para>
-If you want an hi-boot file to export a data type, but you don't want to give its constructors
-(because the constructors aren't used by the SOURCE-importing module), you can write simply:
-</Para>
-
-<Para>
-
-<ProgramListing>
-__interface A 1 404 where
-__export A TA;
-1 data TA
-</ProgramListing>
-
-</Para>
-
-<Para>
-(You must write all the type parameters, but leave out the '=' and everything that follows it.)
-</Para>
-
-<Para>
-<Emphasis>Note:</Emphasis> This is all a temporary solution, a version of the
-compiler that handles mutually recursive modules properly without the manual
-construction of interface files, is (allegedly) in the works.
-</Para>
-
-</Sect2>
-
-</Sect1>
-
- <sect1 id="packages">
- <title>Packages</title>
- <indexterm><primary>packages</primary></indexterm>
-
- <para>Packages are collections of libraries, conveniently grouped
- together as a single entity. The package system is flexible: a
- package may consist of Haskell code, foreign language code (eg. C
- libraries), or a mixture of the two. A package is a good way to
- group together related Haskell modules, and is essential if you
- intend to make the modules into a Windows DLL (see below).</para>
-
- <para>Because packages can contain both Haskell and C libraries, they
- are also a good way to provide convenient access to a Haskell
- layer over a C library.</para>
-
- <para>GHC comes with several packages (see <xref
- linkend="book-hslibs">), and packages can be added/removed from an
- existing GHC installation.</para>
-
- <sect2 id="listing-packages">
- <title>Listing the available packages</title>
- <indexterm><primary>packages</primary>
- <secondary>listing</secondary></indexterm>
-
- <para>To see what packages are currently installed, use the
- <literal>--list-packages</literal> option:</para>
- <indexterm><primary><literal>--list-packages</literal></primary>
- </indexterm>
-
-<screen>
- $ ghc --list-packages
- gmp, rts, std, lang, concurrent, data, net, posix, text, util
-</screen>
-
- <para>Note that your GHC installation might have a slightly
- different set of packages installed.</para>
-
- <para>The <literal>gmp</literal> and <literal>rts</literal>
- packages are always present, and represent the multi-precision
- integer and runtime system libraries respectively. The
- <literal>std</literal> package contains the Haskell prelude.
- The rest of the packages are optional libraries.</para>
-
- </sect2>
-
- <sect2 id="using-packages">
- <title>Using a package</title>
- <indexterm><primary>packages</primary>
- <secondary>using</secondary></indexterm>
-
- <para>To use a package, add the <literal>-package</literal> flag
- to the command line:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>-package <lib></option></term>
- <indexterm><primary>-package <lib> option</primary></indexterm>
- <listitem>
- <para>This option brings into scope all the modules from
- package <literal><lib></literal> (they still have to
- be imported in your Haskell source, however). It also
- causes the relevant libraries to be linked when linking is
- being done.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Some packages depend on other packages, for example the
- <literal>text</literal> package makes use of some of the modules
- in the <literal>lang</literal> package. The package system
- takes care of all these dependencies, so that when you say
- <literal>-package text</literal> on the command line, you
- automatically get <literal>-package lang</literal> too.</para>
- </sect2>
-
- <sect2 id="building-packages">
- <title>Building a package from Haskell source</title>
- <indexterm><primary>packages</primary>
- <secondary>building</secondary></indexterm>
-
- <para>It takes some special considerations to build a new
- package:</para>
-
- <itemizedlist>
- <listitem>
- <para>A package may contain several Haskell modules. A
- package may span many directories, or many packages may
- exist in a single directory. Packages may not be mutually
- recursive.</para>
- </listitem>
-
- <listitem>
- <para>A package has a name
- (e.g. <filename>std</filename>)</para>
- </listitem>
-
- <listitem>
- <para>The Haskell code in a package may be built into one or
- more Unix libraries (e.g. <Filename>libHSfoo.a</Filename>),
- or a single DLL on Windows
- (e.g. <Filename>HSfoo.dll</Filename>). The restriction to a
- single DLL on Windows is that the package system is used to
- tell the compiler when it should make an inter-DLL call
- rather than an intra-DLL call (inter-DLL calls require an
- extra indirection).</para>
- </listitem>
-
- <listitem>
- <para>GHC does not maintain detailed cross-package
- dependency information. It does remember which modules in
- other packages the current module depends on, but not which
- things within those imported things.</para>
- </listitem>
- </itemizedlist>
-
- <para>To compile a module which is to be part of a new package,
- use the <literal>-package-name</literal> option:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>-package-name <foo></option></term>
- <indexterm><primary><literal>-package-name</literal></primary>
- <secondary>option</secondary></indexterm>
- <listitem>
- <para>This option is added to the command line when
- compiling a module that is destined to be part of package
- <literal>foo</literal>. If this flag is omitted then the
- default package <literal>Main</literal> is assumed.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Failure to use the <literal>-package-name</literal> option
- when compiling a package will result in disaster on Windows, but
- is relatively harmless on Unix at the moment (it will just cause
- a few extra dependencies in some interface files). However,
- bear in mind that we might add support for Unix shared libraries
- at some point in the future.</para>
-
- <para>It is worth noting that on Windows, because each package
- is built as a DLL, and a reference to a DLL costs an extra
- indirection, intra-package references are cheaper than
- inter-package references. Of course, this applies to the
- <Filename>Main</Filename> package as well.</para>
-
- </sect2>
- <sect2 id="package-management">
- <title>Package management</title>
- <indexterm><primary>packages</primary>
- <secondary>management</secondary></indexterm>
-
- <para>GHC uses a package configuration file, called
- <literal>packages.conf</literal>, which can be found in your GHC
- install directory. This file isn't intended to be edited
- directly, instead GHC provides options for adding & removing
- packages:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>--add-package</option></term>
- <indexterm><primary><literal>--add-package</literal></primary>
- <secondary>option</secondary></indexterm>
- <listitem>
- <para>Reads a package specification (see below) on stdin,
- and adds it to the database of installed packages. The
- package specification must be a package that isn't already
- installed.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--delete-package <foo></option></term>
- <indexterm><primary><literal>--delete-package</literal></primary>
- <secondary>option</secondary></indexterm>
- <listitem>
- <para>Removes the specified package from the installed
- configuration.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>In both cases, the old package configuration file is saved
- in <literal>packages.conf.old</literal> in your GHC install
- directory, so in an emergency you can always copy this file into
- <literal>package.conf</literal> to restore the old
- settings.</para>
-
- <para>A package specification looks like this:</para>