X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fseparate_compilation.sgml;h=1678413b581254bc5f565a47dd4850ccdb1d5de2;hb=db48bcb95d2812759285177bb5ddadd812ac2724;hp=c124eb2865335035bed54033f1955af10bf743d1;hpb=7d67a216958e8986cf067f96f9e9c7a4101fd29b;p=ghc-hetmet.git
diff --git a/ghc/docs/users_guide/separate_compilation.sgml b/ghc/docs/users_guide/separate_compilation.sgml
index c124eb2..1678413 100644
--- a/ghc/docs/users_guide/separate_compilation.sgml
+++ b/ghc/docs/users_guide/separate_compilation.sgml
@@ -7,7 +7,7 @@
This section describes how GHC supports separate
compilation.
-
+
Interface files
@@ -18,11 +18,14 @@
which contains a module A, say, it generates
an object A.o, and a
companion interface file
- A.hi. 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.
-
+ A.hi. The interface file is merely there
+ to help the compiler compile other modules in the same program.
+ Interfaces are in a binary format, so don't try to look at one;
+ however you can see the contents of an
+ interface file by using GHC with the
+ option (see , below).
+
NOTE: In general, the name of a file containing module
M should be named M.hs
or M.lhs. The only exception to this rule is
@@ -83,11 +86,21 @@
- This flag prepends a colon-separated
+ This flag appends a colon-separated
list of dirs to the “import
- directories” list. See also
- for the significance of using relative and absolute
- pathnames in the list.
+ directories” list, which initially contains a single
+ entry: ..
+
+ This list is scanned before any package directories
+ (see ) when looking for imports,
+ but note that if you have a home module with the same name
+ as a package module then this is likely to cause trouble
+ in other ways, with link errors being the least nasty
+ thing that can go wrong...
+
+ See also for the
+ significance of using relative and absolute pathnames in
+ the list.
@@ -107,25 +120,49 @@
+
+ Finding interfaces for hierarchical modules
+
+ GHC supports a hierarchical module namespace as an
+ extension to Haskell 98 (see ).
+
+ A module name in general consists of a sequence of
+ components separated by dots
+ (‘.’). When looking for
+ interface files for a hierarchical module, the compiler turns
+ the dots into path separators, so for example a module
+ A.B.C becomes A/B/C (or
+ A\B\C under Windows). Then each component of
+ the import directories list is tested in turn; so for example if
+ the list contains directories
+ D1 to
+ Dn, then the compiler
+ will look for the interface in
+ D1/A/B/C.hi first,
+ then D2/A/B/C.hi and
+ so on.
+
+ Note that it's perfectly reasonable to have a module which
+ is both a leaf and a branch of the tree. For example, if we
+ have modules A.B and
+ A.B.C, then A.B's
+ interface file will be in A/B.hi and
+ A.B.C's interface file will be in
+ A/B/C.hi.
+
+ For GHCi and , the search strategy
+ for source files is exactly the same, just replace the
+ .hi suffix in the above description with
+ .hs or .lhs.
+
+
Other options related to interface filesinterface files, options
- file
-
-
-
- The interface output may be directed to another file
- bar2/Wurble.iface with the option
- (not recommended).
- To avoid generating an interface at all, you can say
- -ohi /dev/null, for example.
-
-
-
-
@@ -166,8 +203,20 @@
the labour.
+
+
+
+ file
+
+
+
+ Where file is the name of
+ an interface file, dumps the contents of that interface in
+ a human-readable (ish) format.
+
+
-
+
@@ -248,7 +297,7 @@ OBJS = Main.o Foo.o Bar.o
.SUFFIXES : .o .hs .hi .lhs .hc .s
cool_pgm : $(OBJS)
- rm $@
+ rm -f $@
$(HC) -o $@ $(HC_OPTS) $(OBJS)
# Standard suffix rules
@@ -367,6 +416,14 @@ A.o : B.hi-boot
makefile, then the old dependencies are
deleted first.
+ Don't forget to use the same
+ options on the ghc -M command line as you
+ would when compiling; this enables the dependency generator to
+ locate any imported modules that come from packages. The
+ package modules won't be included in the dependencies
+ generated, though (but see the
+ option below).
+
The dependency generation phase of GHC can take some
additional options, which you may find useful. For historical
reasons, each option passed to the dependency generator from
@@ -439,7 +496,7 @@ ghc -M -optdep-f -optdep.depend ...
-
+ Regard <file> as
"stable"; i.e., exclude it from having dependencies on
@@ -450,12 +507,12 @@ ghc -M -optdep-f -optdep.depend ...
- same as
+ same as
-
+ Regard the colon-separated list of directories
<dirs> as containing stable,
@@ -465,25 +522,23 @@ ghc -M -optdep-f -optdep.depend ...
-
+ Regard <file> as not
"stable"; i.e., generate dependencies on it (if
any). This option is normally used in conjunction with
- the option.
+ the option.
-
+
- Regard prelude libraries as unstable, i.e.,
- generate dependencies on the prelude modules used
- (including Prelude). This option is
- normally only used by the various system libraries. If a
- option is used, dependencies
- will also be generated on the library's
- interfaces.
+ Regard modules imported from packages as unstable,
+ i.e., generate dependencies on the package modules used
+ (including Prelude, and all other
+ standard Haskell libraries). This option is normally
+ only used by the various system libraries.
@@ -548,61 +603,127 @@ import {-# SOURCE #-} A
would look like the following:
-__interface A 1 0 where
-__export A TA{MkTA} ;
-1 newtype TA = MkTA PrelBase.Int ;
+module A where
+newtype TA = MkTA GHC.Base.Int
- The syntax is essentially the same as a normal
- .hi file (unfortunately), so you can
- usually tailor an existing .hi file to make
- a .hi-boot file.
+ The syntax is similar to a normal Haskell source file, but
+ with some important differences:
+
+
+
+ Non-local entities must be qualified with their
+ original defining module. Qualifying
+ by a module which just re-exports the entity won't do. In
+ particular, most Prelude entities aren't
+ actually defined in the Prelude (see for
+ example GHC.Base.Int in the above
+ example). HINT: to find out the fully-qualified name for
+ entities in the Prelude (or anywhere for
+ that matter), try using GHCi's
+ :info command, eg.
+Prelude> :m -Prelude
+> :i IO.IO
+-- GHC.IOBase.IO is a type constructor
+newtype GHC.IOBase.IO a
+...
+
+
+ Only data, type,
+ newtype, class, and
+ type signature declarations may be included.
+
+ 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.
- The number “1” after
- “__interface A” gives the version
- number of module A; it is incremented whenever anything in A's
- interface file changes. In a normal interface file, the
- “0” is the version number of the compiler which
- generated the interface file; it is used to ensure that we don't
- mix-and-match interface files between compiler versions.
- Leaving it as zero in an hi-boot file turns
- off this check.
-
- The number “1” at the beginning of a
- declaration is the version number of that
- declaration: for the purposes of .hi-boot
- files these can all be set to 1. All names must be fully
- qualified with the original module that an
- object comes from: for example, the reference to
- Int in the interface for A
- comes from PrelBase, which is a module
- internal to GHC's prelude. It's a pain, but that's the way it
- is.
-
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:
-__interface A 1 0 where
-__export A TA;
-1 data TA
+module A where
+data TA
(You must write all the type parameters, but leave out the
'=' and everything that follows it.)
-
- Note: 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.
+
+
+
+ Orphan modules and instance declarations
+
+ Haskell specifies that when compiling module M, any instance
+declaration in any module "below" M is visible. (Module A is "below"
+M if A is imported directly by M, or if A is below a module that M imports directly.)
+In principle, GHC must therefore read the interface files of every module below M,
+just in case they contain an instance declaration that matters to M. This would
+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:
+
+ An orphan module
+ orphan module
+ contains at least one orphan instance or at
+ least one orphan rule.
+
+ An instance declaration in a module M is an orphan instance if
+ orphan instance
+ none of the type constructors
+ or classes mentioned in the instance head (the part after the ``=>'') are declared
+ in M.
+
+ Only the instance head counts. In the example above, it is not good enough for C's declaration
+ to be in module A; it must be the declaration of D or T.
+
+
+ A rewrite rule in a module M is an orphan rule
+ orphan rule
+ if none of the variables, type constructors,
+ or classes that are free in the left hand side of the rule are declared in M.
+
+
+
+
+ GHC identifies orphan modules, and visits the interface file of
+every orphan module below the module being compiled. This is usually
+wasted work, but there is no avoiding it. You should therefore do
+your best to have as few orphan modules as possible.
+
+
+
+ You can identify an orphan module by looking in its interface
+file, M.hi, using the
+. If there is a ``!'' on the first line,
+GHC considers it an orphan module.
+
+
+