X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fseparate_compilation.sgml;h=e1052bd163d40c45ee0c161a17ed5b67d87e73d3;hb=2dfd507259664e6f28df4a9467a8de34d01d70a0;hp=6595b88435f75914a4c6cb4381eca7e298c92efe;hpb=dc801dc275fb8f81d482535b4d6317e234bb10f8;p=ghc-hetmet.git
diff --git a/ghc/docs/users_guide/separate_compilation.sgml b/ghc/docs/users_guide/separate_compilation.sgml
index 6595b88..e1052bd 100644
--- a/ghc/docs/users_guide/separate_compilation.sgml
+++ b/ghc/docs/users_guide/separate_compilation.sgml
@@ -11,7 +11,7 @@
Note that this section is written with
hierarchical modules in mind (see ); hierarchical modules are an
+ linkend="hierarchical-modules"/>); hierarchical modules are an
extension to Haskell 98 which extends the lexical syntax of
module names to include a dot ‘.’. Non-hierarchical
modules are thus a special case in which none of the module names
@@ -38,7 +38,7 @@
should be placed in the file A/B/C.hs,
relative to some base directory. GHC's behaviour if this rule
is not followed is fully defined by the following section ().
+ linkend="output-files"/>).
@@ -64,7 +64,7 @@
types of exported functions, definitions of data types, and so
on. It is stored in a binary format, so don't try to read one;
use the option instead (see ).
+ linkend="hi-options"/>).
You should think of the object file and the interface file as a
pair, since the interface file is in a sense a compiler-readable
@@ -121,7 +121,7 @@
For any module that is imported, GHC requires that the
name of the module in the import statement exactly matches the
name of the module in the interface file (or source file) found
- using the strategy specified in .
+ using the strategy specified in .
This means that for most modules, the source file name should
match the module name.
@@ -203,7 +203,7 @@
This isn't the whole story: GHC also looks for modules in
pre-compiled libraries, known as packages. See the section on
- packages (), for details.
+ packages (), for details.
@@ -260,9 +260,9 @@
Redirects object files to directory
dir. For example:
-
+
$ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
-
+The object files, Foo.o,
Bar.o, and
@@ -335,7 +335,7 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
Similarly, the
suffix will change the
.hi file suffix for non-system
- interface files (see ).
+ interface files (see ).Finally, the option
suffix will change the
@@ -346,11 +346,11 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
game is particularly useful if you want to compile a
program both with and without profiling, in the same
directory. You can say:
-
- ghc ...
+
+ ghc ...
to get the ordinary version, and
-
- ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all
+
+ ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all
to get the profiled version.
@@ -423,7 +423,7 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
Instructs the GHC driver not to delete any of its
temporary files, which it normally keeps in
/tmp (or possibly elsewhere; see ). Running GHC with
+ linkend="temp-files"/>). Running GHC with
will show you what temporary files
were generated along the way.
@@ -448,30 +448,30 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
in /tmp (or wherever your
installation thinks temporary files should go), you may
use the -tmpdir
- <dir> option option to specify
+ <dir>-tmpdir
+ <dir> option option to specify
an alternate directory. For example, says to put temporary files in the current
working directory.
- Alternatively, use your TMPDIR
- environment variable.TMPDIR
- environment variable Set it to the
+ Alternatively, use your TMPDIR
+ environment variable.TMPDIR
+ environment variable Set it to the
name of the directory where temporary files should be put.
GCC and other programs will honour the
- TMPDIR variable as well.
+ TMPDIR variable as well.Even better idea: Set the
- DEFAULT_TMPDIR make variable when
+ DEFAULT_TMPDIR make variable when
building GHC, and never worry about
- TMPDIR again. (see the build
+ TMPDIR again. (see the build
documentation).
-
+ Other options related to interface filesinterface files, options
@@ -589,8 +589,8 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
required”. What a beautiful sight!
Patrick Sansom had a workshop paper about how all this is
- done (though the details have changed quite a bit). Ask him if you want a
+ done (though the details have changed quite a bit). Ask him if you want a
copy.
@@ -604,7 +604,7 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
Makefile to use with GHC, assuming you name
your source files the same as your modules. Thus:
-
+
HC = ghc
HC_OPTS = -cpp $(EXTRA_HC_OPTS)
@@ -630,17 +630,17 @@ cool_pgm : $(OBJS)
# 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
-
+(Sophisticated make variants may
achieve some of the above more elegantly. Notably,
gmake's pattern rules let you write the more
comprehensible:
-
+
%.o : %.lhs
$(HC) -c $< $(HC_OPTS)
-
+What we've shown should work with any
make.)
@@ -654,9 +654,9 @@ Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz
Note the inter-module dependencies at the end of the
Makefile, which take the form
-
+
Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
-
+They tell make that if any of
Foo.o, Foo.hc or
@@ -677,10 +677,10 @@ Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
automatically generating the required dependencies. Add the
following to your Makefile:
-
+
depend :
ghc -M $(HC_OPTS) $(SRCS)
-
+Now, before you start compiling, and any time you change
the imports in your program, do
@@ -716,7 +716,7 @@ import {-# SOURCE #-} B ...blah...
A.o : B.hi-boot
- (See for details of
+ (See for details of
hi-boot style interface files.) If
A imports multiple modules, then there will
be multiple lines with A.o as the
@@ -873,7 +873,7 @@ ghc -M -optdep-f -optdep.depend ...
Currently, the compiler does not have proper support for
dealing with mutually recursive modules:
-
+
module A where
import B
@@ -891,7 +891,7 @@ data TB = MkTB !Int
g :: TA -> TB
g (MkTA x) = MkTB x
-
+When compiling either module A and B, the compiler will
try (in vain) to look for the interface file of the other. So,
@@ -906,9 +906,9 @@ g (MkTA x) = MkTB x
files importing,
hi-boot files
-
+
import {-# SOURCE #-} A
-
+The hand-written interface need only contain the bare
minimum of information needed to get the bootstrapping process
@@ -920,10 +920,10 @@ import {-# SOURCE #-} A
For the example at hand, the boot interface file for A
would look like the following:
-
+
module A where
newtype TA = MkTA GHC.Base.Int
-
+The syntax is similar to a normal Haskell source file, but
with some important differences:
@@ -956,12 +956,12 @@ newtype GHC.IOBase.IO a
For data or newtype declaration, you may omit all
the constructors, by omitting the '=' and everything that follows it:
-
+
module A where
data TA
-
+
In a source program
- this would declare TA to have no constructors (a GHC extension: see ),
+ this would declare TA to have no constructors (a GHC extension: see ),
but in an hi-boot file it means "I don't know or care what the construtors are".
This is the most common form of data type declaration, because it's easy to get right.
@@ -976,7 +976,7 @@ module A where
Regardless of whether you write the constructors, you must write all the type parameters,
including their kinds
- if they are not '*'. (You can give explicit kinds in source files too (),
+ if they are not '*'. (You can give explicit kinds in source files too (),
but you must do so in hi-boot files.)
@@ -987,8 +987,8 @@ operations. We could lift this restriction if it became tiresome.Notice that we only put the declaration for the newtype
TA in the hi-boot file,
- not the signature for f, since
- f isn't used by B.
+ not the signature for f, since
+ f isn't used by B.
@@ -1006,21 +1006,21 @@ be a disaster in practice, so GHC tries to be clever.
In particular, if an instance declaration is in the same module as the definition
of any type or class mentioned in the head of the instance declaration, then
GHC has to visit that interface file anyway. Example:
-
+
module A where
instance C a => D (T a) where ...
data T a = ...
-
+ The instance declaration is only relevant if the type T is in use, and if
so, GHC will have visited A's interface file to find T's definition. The only problem comes when a module contains an instance declaration
and GHC has no other reason for visiting the module. Example:
-
+
module Orphan where
instance C a => D (T a) where ...
class C a where ...
-
+
Here, neither D nor T is declared in module Orphan.
We call such modules ``orphan modules'',
defined thus: