[[project @ 2003-09-04 13:58:12 by simonmar] simonmar**20030904135812 - Document -e - Rearrange the documentation on "modes". I've moved the list of modes from the beginning of "Using GHC", to a subsection a little later, and the sections describing make-mode and batch-mode are now further subsections of this. - Add missing modes to the list: -M and --mk-dll. ] { hunk ./ghc/docs/users_guide/using.sgml 7 - GHC can work in one of three “modes”: - - - - ghc - ––interactive - - interactive mode - - ghci - - - Interactive mode, which is also available as - ghci. Interactive mode is described in - more detail in . - - - - - ghc - ––make - - make mode - - - - - In this mode, GHC will build a multi-module Haskell - program automatically, figuring out dependencies for itself. - If you have a straightforward Haskell program, this is likely - to be much easier, and faster, than using - make. - - - - - - ghc - - -E - -C - -S - -c - - - - - - - - This is the traditional batch-compiler mode, in which - GHC can compile source files one at a time, or link objects - together into an executable. - - - - hunk ./ghc/docs/users_guide/using.sgml 190 + + Modes of operation + + GHC's behaviour is firstly controlled by a mode flag. Only + one of these flags may be given, but it does not necessarily need + to be the first option on the command-line. The available modes + are: + + + + ghc + ––interactive + + interactive mode + + ghci + + + Interactive mode, which is also available as + ghci. Interactive mode is described in + more detail in . + + + + + ghc + ––make + + make mode + + + + + In this mode, GHC will build a multi-module Haskell + program automatically, figuring out dependencies for itself. + If you have a straightforward Haskell program, this is + likely to be much easier, and faster, than using + make. Make mode is described in . + + + + + ghc + –e expr + + eval mode + + + Expression-evaluation mode. This is very similar to + interactive mode, except that there is a single expression + to evaluate (expr) which is given + on the command line. See for + more details. + + + + + + ghc + + -E + -C + -S + -c + + + + + + + + This is the traditional batch-compiler mode, in which + GHC can compile source files one at a time, or link objects + together into an executable. This mode also applies if + there is no other mode flag specified on the command line, + in which case it means that the specified files should be + compiled and then linked to form a program. See . + + + + + ghc + –M + dependency-generation mode + + + Dependency-generation mode. In this mode, GHC can be + used to generate dependency information suitable for use in + a Makefile. See . + + + + + ghc + ––mk-dll + dependency-generation mode + + + DLL-creation mode (Windows only). See . + + + + + + Using <command>ghc</command> <option>––make</option> + + + + separate compilation + + + When given the option, + GHC will build a multi-module Haskell program by following + dependencies from a single root module (usually + Main). For example, if your + Main module is in a file called + Main.hs, you could compile and link the + program like this: + + +ghc ––make Main.hs + + + The command line may contain any number of source file + names or module names; GHC will figure out all the modules in + the program by following the imports from these initial modules. + It will then attempt to compile each module which is out of + date, and finally if there is a Main module, + the program will also be linked into an executable. + + The main advantages to using ghc + ––make over traditional + Makefiles are: + + + + GHC doesn't have to be restarted for each compilation, + which means it can cache information between compilations. + Compiling a muli-module program with ghc + ––make can be up to twice as fast as + running ghc individually on each source + file. + + + You don't have to write a + Makefile. + + Makefilesavoiding + + + GHC re-calculates the dependencies each time it is + invoked, so the dependencies never get out of sync with the + source. + + + + Any of the command-line options described in the rest of + this chapter can be used with + , but note that any options + you give on the command line will apply to all the source files + compiled, so if you want any options to apply to a single source + file only, you'll need to use an OPTIONS + pragma (see ). + + If the program needs to be linked with additional objects + (say, some auxilliary C code), then the object files can be + given on the command line and GHC will include them when linking + the executable. + + Note that GHC can only follow dependencies if it has the + source file available, so if your program includes a module for + which there is no source file, even if you have an object and an + interface file for the module, then GHC will complain. The + exception to this rule is for package modules, which may or may + not have source files. + + The source files for the program don't all need to be in + the same directory; the option can be used + to add directories to the search path (see ). + + + + Expression evaluation mode + + This mode is very similar to interactive mode, except that + there is a single expression to evaluate which is specified on + the command line as an argument to the + option: + + +ghc -e expr + + + Haskell source files may be named on the command line, and + they will be loaded exactly as in interactive mode. The + expression is evaluated in the context of the loaded + modules. + + For example, to load and run a Haskell program containing + a module Main, we might say + + +ghc -e Main.main Main.hs + + + or we can just use this mode to evaluate expressions in + the context of the Prelude: + + +$ ghc -e "interact (unlines.map reverse.lines)" +hello +olleh + + + + + Batch compiler mode + + In this mode, GHC will compile one or more source files + given on the command line. + + The first phase to run is determined by each input-file + suffix, and the last phase is determined by a flag. If no + relevant flag is present, then go all the way through linking. + This table summarises: + + + + + + + + + + + Phase of the compilation system + Suffix saying “start here” + Flag saying “stop after” + (suffix of) output file + + + + + literate pre-processor + .lhs + - + .hs + + + + C pre-processor (opt.) + .hs (with + ) + + .hspp + + + + Haskell compiler + .hs + , + .hc, .s + + + + C compiler (opt.) + .hc or .c + + .s + + + + assembler + .s + + .o + + + + linker + other + - + a.out + + + + + + + + + + + Thus, a common invocation would be: + + +ghc -c Foo.hs + + to compile the Haskell source file + Foo.hs to an object file + Foo.o. + + Note: What the Haskell compiler proper produces depends on + whether a native-code generatornative-code + generator is used (producing assembly + language) or not (producing C). See for more details. + + Note: C pre-processing is optional, the + + flag turns it on. See for more + details. + + Note: The option -E + option runs just the pre-processing passes + of the compiler, dumping the result in a file. Note that this + differs from the previous behaviour of dumping the file to + standard output. + + + hunk ./ghc/docs/users_guide/using.sgml 647 - - - Using <command>ghc</command> <option>––make</option> - - - - separate compilation - - - When given the option, GHC will - build a multi-module Haskell program by following dependencies - from a single root module (usually Main). For - example, if your Main module is in a file - called Main.hs, you could compile and link - the program like this: - - -ghc ––make Main.hs - - - The command line may contain any number of source file names - or module names; GHC will figure out all the modules in the - program by following the imports from these initial modules. It - will then attempt to compile each module which is out of date, and - finally if there is a Main module, the program - will also be linked into an executable. - - The main advantages to using ghc ––make - over traditional Makefiles are: - - - - GHC doesn't have to be restarted for each compilation, - which means it can cache information between compilations. - Compiling a muli-module program with ghc - ––make can be up to twice as fast as running - ghc individually on each source - file. - - - You don't have to write a - Makefile. - - Makefilesavoiding - - - GHC re-calculates the dependencies each time it is - invoked, so the dependencies never get out of sync with the - source. - - - - Any of the command-line options described in the rest of - this chapter can be used with , but note - that any options you give on the command line will apply to all - the source files compiled, so if you want any options to apply to - a single source file only, you'll need to use an - OPTIONS pragma (see ). - - If the program needs to be linked with additional objects - (say, some auxilliary C code), then the object files can be - given on the command line and GHC will include them when linking - the executable. - - Note that GHC can only follow dependencies if it has the - source file available, so if your program includes a module for - which there is no source file, even if you have an object and an - interface file for the module, then GHC will complain. The - exception to this rule is for package modules, which may or may - not have source files. - - The source files for the program don't all need to be in the - same directory; the option can be used to add - directories to the search path (see ). - - - - - GHC without <option>––make</option> - - Without , GHC will compile one or - more source files given on the command line. - - The first phase to run is determined by each input-file - suffix, and the last phase is determined by a flag. If no - relevant flag is present, then go all the way through linking. - This table summarises: - - - - - - - - - - - Phase of the compilation system - Suffix saying “start here” - Flag saying “stop after” - (suffix of) output file - - - - - literate pre-processor - .lhs - - - .hs - - - - C pre-processor (opt.) - - .hs (with - ) - - .hspp - - - - Haskell compiler - .hs - , - .hc, .s - - - - C compiler (opt.) - .hc or .c - - .s - - - - assembler - .s - - .o - - - - linker - other - - - a.out - - - - - - - - - - - Thus, a common invocation would be: ghc -c - Foo.hs - - Note: What the Haskell compiler proper produces depends on - whether a native-code generatornative-code - generator is used (producing assembly - language) or not (producing C). See for more details. - - Note: C pre-processing is optional, the - - flag turns it on. See for more details. - - Note: The option -E - option runs just the pre-processing passes - of the compiler, dumping the result in a file. Note that this - differs from the previous behaviour of dumping the file to - standard output. - }