X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fseparate_compilation.sgml;h=1678413b581254bc5f565a47dd4850ccdb1d5de2;hb=9490f5ceb4cdb840eb94bdfc53fe593e130a42c3;hp=45e6c9c251656a3f25101d8da56c98d7fcddf51f;hpb=ec655d31e7a73d0e2b9eb160faa7ebd7c9fe3577;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/separate_compilation.sgml b/ghc/docs/users_guide/separate_compilation.sgml index 45e6c9c..1678413 100644 --- a/ghc/docs/users_guide/separate_compilation.sgml +++ b/ghc/docs/users_guide/separate_compilation.sgml @@ -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 @@ -117,6 +120,43 @@ + + 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 @@ -163,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. + + - + @@ -245,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 @@ -551,60 +603,55 @@ 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. @@ -668,9 +715,12 @@ 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. If there is a ``!'' on -the first line, GHC considers it an orphan module. + + + 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.