X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fusing.sgml;h=0abae40ba1d51b632774ada27f9950c2fad0c691;hb=0dfa678a3be85a7b8353b510a026ae684b1ee7cc;hp=cf0b95ab944ad73eb451f662b347fd70aa0bb9f2;hpb=05a9c035960327b23bad8d8dc501141b183f33b5;p=ghc-hetmet.git
diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml
index cf0b95a..0abae40 100644
--- a/ghc/docs/users_guide/using.sgml
+++ b/ghc/docs/users_guide/using.sgml
@@ -4,63 +4,6 @@
GHC, usingusing GHC
- 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.
-
-
-
-
Options overview
@@ -162,14 +105,9 @@ module X where
pragma in a source file or set from the GHCi command-line with
:set.
- As a rule of thumb, all the language options are dynamic, as
- are the warning options and the debugging options. The rest are
- static, with the notable exceptions of ,
- , ,
- , and .
-
- The flag reference tables () lists
- the status of each flag.
+ As a rule of thumb, options which relate to filenames are
+ static, and the rest are dynamic. The flag reference tables () lists the status of each flag.
@@ -244,6 +182,332 @@ module X where
+
+ 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
+ –eexpr
+
+ 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 ghc
+
+
+
+ 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.
+
+
+
Help and verbosity options
@@ -341,7 +605,9 @@ module X where
+
+ Print a one-line string including GHC's version number.
@@ -374,444 +640,7 @@ module X where
-
- Using ghc
-
-
-
- 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 must contain one source file or module
- name; GHC will figure out all the modules in the program by
- following the imports from this initial module. It will then
- attempt to compile each module which is out of date, and finally
- if the top module is Main, 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), these can be specified on the
- command line as usual.
-
- 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
-
- 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.
-
-
-
- Re-directing the compilation output(s)
-
- output-directing options
- redirecting compilation output
-
-
-
-
-
-
-
- GHC's compiled output normally goes into a
- .hc, .o, etc.,
- file, depending on the last-run compilation phase. The
- option -o
- option re-directs the output of that
- last-run phase to file foo.
-
- Note: this “feature” can be
- counterintuitive: ghc -C -o foo.o foo.hs
- will put the intermediate C code in the file
- foo.o, name notwithstanding!
-
- Note: on Windows, if the result is an executable file, the
- extension ".exe" is added if the specified filename
- does not already have an extension. Thus
-
- ghc -o foo Main.hs
-
- will compile and link the module Main.hs, and put the
- resulting executable in foo.exe (not foo).
-
-
-
-
-
-
-
-
- The option isn't of much use if
- you have several input files…
- Non-interface output files are normally put in the same
- directory as their corresponding input file came from. You
- may specify that they be put in another directory using the
- -odir
- <dir> option (the “Oh,
- dear” option). For example:
-
-
-% ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
-
-
- The output files, Foo.o,
- Bar.o, and
- Bumble.o would be put into a
- subdirectory named after the architecture of the executing
- machine (sun4,
- mips, etc). The directory must already
- exist; it won't be created.
-
- Note that the option does
- not affect where the interface files
- are put. In the above example, they would still be put in
- parse/Foo.hi,
- parse/Bar.hi, and
- gurgle/Bumble.hi.
-
-
-
-
- file
-
-
-
- The interface output may be directed to another file
- bar2/Wurble.iface with the option
- (not
- recommended).
-
- WARNING: if you redirect the interface file somewhere
- that GHC can't find it, then the recompilation checker may
- get confused (at the least, you won't get any recompilation
- avoidance). We recommend using a combination of
- and options
- instead, if possible.
-
- To avoid generating an interface at all, you could use
- this option to redirect the interface into the bit bucket:
- -ohi /dev/null, for example.
-
-
-
-
- directory
-
-
-
- Redirects all generated interface files into
- directory, instead of the default
- which is to place the interface file in the same directory
- as the source file.
-
-
-
-
- suffix
- suffix
- suffix
-
-
-
-
- EXOTICA: The
- suffix will change the
- .o file suffix for object files to
- whatever you specify. We use this when compiling libraries,
- so that objects for the profiling versions of the libraries
- don't clobber the normal ones.
-
- Similarly, the
- suffix will change the
- .hi file suffix for non-system interface
- files (see ).
-
- Finally, the option
- suffix will change the
- .hc file suffix for compiler-generated
- intermediate C files.
-
- The /
- game is particularly useful if you want to compile a program both with and without
- profiling, in the same directory. You can say:
-
- ghc ...
-
- to get the ordinary version, and
-
- ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all
-
- to get the profiled version.
-
-
-
-
-
- Keeping Intermediate Files
- intermediate files, saving
-
- .hc files, saving
-
- .s files, saving
-
-
-
- The following options are useful for keeping certain
- intermediate files around, when normally GHC would throw these
- away after compilation:
-
-
-
-
-
-
-
-
- Keep intermediate .hc files when
- doing .hs-to-.o
- compilations via C (NOTE: .hc files
- aren't generated when using the native code generator, you
- may need to use to force them
- to be produced).
-
-
-
-
-
-
-
-
-
- Keep intermediate .s files.
-
-
-
-
-
-
-
-
-
- Keep intermediate .raw-s files.
- These are the direct output from the C compiler, before
- GHC does “assembly mangling” to produce the
- .s file. Again, these are not produced
- when using the native code generator.
-
-
-
-
-
-
-
-
-
- temporary files
- keeping
-
-
- 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
- will show you what temporary files
- were generated along the way.
-
-
-
-
-
-
- Redirecting temporary files
-
-
- temporary files
- redirecting
-
-
-
-
-
-
-
- If you have trouble because of running out of space
- in /tmp (or wherever your
- installation thinks temporary files should go), you may
- use the -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
- name of the directory where temporary files should be put.
- GCC and other programs will honour the
- TMPDIR variable as well.
-
- Even better idea: Set the
- DEFAULT_TMPDIR make variable when
- building GHC, and never worry about
- TMPDIR again. (see the build
- documentation).
-
-
-
-
-
-
+ &separate;
Warnings and sanity-checking
@@ -825,7 +654,7 @@ ghc ––make Main.hs
generated during compilation. By default, you get a standard set
of warnings which are generally likely to indicate bugs in your
program. These are:
- ,
+ ,
,
,
, and
@@ -864,6 +693,15 @@ ghc ––make Main.hs
+
+ :
+
+
+ Makes any warning into a fatal error. Useful so that you don't
+ miss warnings when doing batch compilation.
+
+
+
The full set of warning options is described below. To turn
@@ -977,6 +815,18 @@ g [] = 2
an instance declaration is missing one or more methods, and
the corresponding class declaration has no default
declaration for them.
+ The warning is suppressed if the method name
+ begins with an underscore. Here's an example where this is useful:
+
+ class C a where
+ _simpleFn :: a -> String
+ complexFn :: a -> a -> String
+ complexFn x y = ... _simpleFn ...
+
+ The idea is that: (a) users of the class will only call complexFn;
+ never _simpleFn; and (b)
+ instance declarations can define either complexFn or _simpleFn.
+
@@ -1044,6 +894,20 @@ f "2" = 2
patterns that can fail, eg. \(x:xs)->....
Normally, these aren't treated as incomplete patterns by
.
+ ``Lambda-bound patterns'' includes all places where there is a single pattern,
+ including list comprehensions and do-notation. In these cases, a pattern-match
+ failure is quite legitimate, and triggers filtering (list comprehensions) or
+ the monad fail operation (monads). For example:
+
+ f :: [Maybe a] -> [a]
+ f xs = [y | Just y <- xs]
+
+ Switching on will elicit warnings about
+ these probably-innocent cases, which is why the flag is off by default.
+ The deriving( Read ) mechanism produces monadic code with
+ pattern matches, so you will also get misleading warnings about the compiler-generated
+ code. (This is arguably a Bad Thing, but it's awkward to fix.)
+
@@ -1101,9 +965,12 @@ f "2" = 2
Report all unused variables which arise from pattern
matches, including patterns consisting of a single variable.
For instance f x y = [] would report
- x and y as unused. To
- eliminate the warning, all unused variables can be replaced
- with wildcards.
+ x and y as unused. The
+ warning is suppressed if the variable name begins with an underscore, thus:
+
+ f _x = True
+
+
@@ -1118,7 +985,6 @@ f "2" = 2
- &separate;
&packages;
@@ -1145,13 +1011,11 @@ f "2" = 2
following “packages” of optimisations (or lack
thereof) should suffice.
- Once you choose a
- “package,” stick with it—don't chop and
- change. Modules' interfaces will change
- with a shift to a new option, and you may
- have to recompile a large chunk of all importing modules before
- your program can again be run safely (see ).
+ Note that higher optimisation levels cause more
+ cross-module optimisation to be performed, which can have an
+ impact on how much of your program needs to be recompiled when
+ you change something. This is one reaosn to stick to
+ no-optimisation when developing code.
@@ -1188,6 +1052,10 @@ f "2" = 2
Means: “Generate good-quality code without
taking too long about it.” Thus, for example:
ghc -c -O Main.lhs
+
+ currently also implies
+ . This may change in the
+ future.
@@ -1216,7 +1084,7 @@ f "2" = 2
-Ofile <file> optionoptimising, customised
- (NOTE: not supported yet in GHC 5.x. Please ask if
+ (NOTE: not supported since GHC 4.x. Please ask if
you're interested in this.)For those who need absolute
@@ -1238,7 +1106,7 @@ f "2" = 2
We don't use a flag for day-to-day
work. We use to get respectable speed;
e.g., when we want to measure something. When we want to go for
- broke, we tend to use (and we go for
+ broke, we tend to use (and we go for
lots of coffee breaks).The easiest way to see what (etc.)
@@ -1860,7 +1728,7 @@ statements or clauses.
&runtime;
- Generating External Core Files
+ Generating and compiling External Core Filesintermediate code generation
@@ -1876,6 +1744,10 @@ statements or clauses.
files is different (though similar) to the Core output format generated
for debugging purposes ().
+ The Core format natively supports notes which you can add to
+ your source code using the CORE pragma (see ).
+
@@ -1890,6 +1762,10 @@ statements or clauses.
+GHC can also read in External Core files as source; just give the .hcr file on
+the command line, instead of the .hs or .lhs Haskell source.
+A current infelicity is that you need to give teh -fglasgow-exts flag too, because
+ordinary Haskell 98, when translated to External Core, uses things like rank-2 types.
&debug;