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 files interface 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: