X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fseparate_compilation.xml;h=fc44fe66b699ba1a08e8a392005b20213350143a;hb=c76d8afbca85519fface96bd11009eccd959b93a;hp=cb80aadd443efe817d0552807db8a71133cf6c4c;hpb=60bbba360c8ed5267f10e6b599b8884b6bc2e4ce;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/separate_compilation.xml b/ghc/docs/users_guide/separate_compilation.xml index cb80aad..fc44fe6 100644 --- a/ghc/docs/users_guide/separate_compilation.xml +++ b/ghc/docs/users_guide/separate_compilation.xml @@ -253,6 +253,23 @@ Main.hs, and put the resulting executable in foo.exe (not foo). + + If you use ghc --make and you don't + use the , the name GHC will choose + for the executable will be based on the name of the file + containing the module Main. + Note that with GHC the Main module doesn't + have to be put in file Main.hs. + Thus both + + ghc --make Prog + + and + + ghc --make Prog.hs + + will produce Prog (or + Prog.exe if you are on Windows). @@ -326,6 +343,23 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` + dir + + + + Redirects all generated FFI stub files into + dir. Stub files are generated when the + Haskell source contains a foreign export or + foreign import "&wrapper" declaration (see ). The + option behaves in exactly the same way as + and with respect to hierarchical + modules. + + + + + suffix @@ -369,7 +403,7 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` - + Keeping Intermediate Files intermediate files, saving @@ -653,20 +687,6 @@ version of A.hs, thus: module A where newtype TA = MkTA Int -A hs-boot file is compiled by GHC, just like a hs file: - - ghc -c A.hs-boot - -Just as compiling A.hs produces an -interface file A.hi, and an object file -A.o, so compiling A.hs-boot -produces an interface file -A.hi-boot, and an pseudo-object file -A.o-boot. The interface file -A.hi-boot has exactly the same format as any -other interface file. The pseudo-object file is empty (don't link it!), but it is -very useful when using a Makefile, to record when the A.hi-boot was -last brought up to date. To compile these three files, issue the following commands: @@ -681,30 +701,64 @@ last brought up to date. The file A.hs-boot is a programmer-written source file. It must live in the same directory as its parent source file A.hs. - (Currently, if you use a literate source file A.lhs you must - also use a literate boot file, A.lhs-boot.) + Currently, if you use a literate source file A.lhs you must + also use a literate boot file, A.lhs-boot; and vice versa. - The hi-boot generated by compiling a hs-boot - file is in machine-generated binary format. - You can display its contents with ghc --show-iface. If you - specify a directory for interface files, the flag, then that affects - hi-boot files too.b - - Hs-boot files are written in a subset of Haskell. In particular, the module - exports and imports, and the scoping rules are exactly the same as in Haskell. Hence, to - mention a non-Prelude type or class, you must import it. - - When a hs-boot file A.hs-boot + + A hs-boot file is compiled by GHC, just like a hs file: + + ghc -c A.hs-boot + +When a hs-boot file A.hs-boot is compiled, it is checked for scope and type errors. When its parent module A.hs is compiled, the two are compared, and an error is reported if the two are inconsistent. + + Just as compiling A.hs produces an + interface file A.hi, and an object file + A.o, so compiling + A.hs-boot produces an interface file + A.hi-boot, and an pseudo-object file + A.o-boot: + + + + The pseudo-object file A.o-boot is + empty (don't link it!), but it is very useful when using a + Makefile, to record when the A.hi-boot was + last brought up to date (see ). + + + + The hi-boot generated by compiling a + hs-boot file is in the same + machine-generated binary format as any other GHC-generated + interface file (e.g. B.hi). You can + display its contents with ghc + --show-iface. If you specify a directory for + interface files, the flag, then that + affects hi-boot files + too. + + + + If hs-boot files are considered distinct from their parent source files, and if a {-# SOURCE #-} import is considered to refer to the - hs-boot file, then the module import graph must have no cycles. The ghc -M - will report an error if a cycle is found. + hs-boot file, then the module import graph must have no cycles. The command + ghc -M will report an error if a cycle is found. + + + A module M that is + {-# SOURCE #-}-imported in a program will usually also be + ordinarily imported elsewhere. If not, ghc --make + automatically adds M to the set of moudles it tries to + compile and link, to ensure that M's implementation is included in + the final program. @@ -714,10 +768,13 @@ A hs-boot file need only contain the bare started. For example, it doesn't need to contain declarations for everything that module A exports, only the things required by the - module that imports A recursively. + module(s) that import A recursively. A hs-boot file is written in a subset of Haskell: - The module header, and import statements, are exactly as in Haskell. + The module header (including the export list), and import statements, are exactly as in +Haskell, and so are the scoping rules. + Hence, to mention a non-Prelude type or class, you must import it. + There must be no value declarations, but there can be type signatures for values. For example: @@ -823,16 +880,16 @@ Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz doing…nothing. Which is true. Note that the suffix rules are all repeated twice, once for normal Haskell source files, and once for hs-boot - files (see ). + files (see ). - Note the inter-module dependencies at the end of the - Makefile, which take the form + Note also 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 + They tell make that if any of Foo.o, Foo.hc or Foo.s have an earlier modification date than Baz.hi, then the out-of-date file must be @@ -843,6 +900,7 @@ Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz + Dependency generation dependencies in Makefiles @@ -898,6 +956,14 @@ M.o : X.hi-boot ghc traces the dependencies, just like ghc --make (a new feature in GHC 6.4). + Note that ghc -M needs to find a source + file for each module in the dependency graph, so that it can + parse the import declarations and follow dependencies. Any pre-compiled + modules without source files must therefore belong to a + packageThis is a change in behaviour relative to 6.2 and + earlier. + . + By default, ghc -M generates all the dependencies, and then concatenates them onto the end of makefile (or @@ -915,7 +981,7 @@ M.o : X.hi-boot 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). + option below). The dependency generation phase of GHC can take some additional options, which you may find useful. For historical @@ -939,6 +1005,17 @@ ghc -M -optdep-f -optdep.depend ... + + + Print a full list of the module depenencies to stdout. + (This is the standard verbosity flag, so the list will + also be displayed with and + ; + .) + + + + file Use file as the makefile, @@ -1026,12 +1103,16 @@ ghc -M -optdep-f -optdep.depend ... - + Regard modules imported from packages as unstable, - i.e., generate dependencies on the package modules used + i.e., generate dependencies on any imported package modules (including Prelude, and all other - standard Haskell libraries). This option is normally + standard Haskell libraries). Dependencies are not traced + recursively into packages; dependencies are only generated for + home-package modules on external-package modules directly imported + by the home package module. + This option is normally only used by the various system libraries.