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 files interface 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. + + +