[[project @ 2001-02-15 17:33:53 by simonmar]
simonmar**20010215173353
More documentation rewriting... I'm particularly proud of the "flag
reference" section, please check it out.
] {
addfile ./ghc/docs/users_guide/flags.sgml
addfile ./ghc/docs/users_guide/packages.sgml
addfile ./ghc/docs/users_guide/phases.sgml
addfile ./ghc/docs/users_guide/separate_compilation.sgml
hunk ./ghc/docs/users_guide/debugging.sgml 14
-
-Replacing the program for one or more phases.
-
-
-
-GHC phases, changing
-phases, changing GHC
-You may specify that a different program be used for one of the phases
-of the compilation system, in place of whatever the driver ghc has
-wired into it. For example, you might want to try a different
-assembler. The
--pgm<phase><stuff>
-option option to ghc will cause it to use <program-name>
-for phase <phase-code>, where the codes to indicate the phases are:
-
-
-
-
-
-
-
-
-
-code
-phase
-
-
-
-
-L
- literate pre-processor
-
-
-
-P
- C pre-processor (if -cpp only)
-
-
-
-C
- Haskell compiler
-
-
-
-c
- C compiler
-
-
-
-a
- assembler
-
-
-
-l
- linker
-
-
-
-dep
- Makefile dependency generator
-
-
-
-
-
-
-
-
-
-
-
-Forcing options to a particular phase.
-
-
-
-forcing GHC-phase options
-
-
-
-The preceding sections describe driver options that are mostly
-applicable to one particular phase. You may also force a
-specific option to be passed to a particular phase
-<phase-code> by feeding the driver the option
-.-opt<phase><stuff>
-option The codes to indicate the phases are the same as in the
-previous section.
-
-
-
-So, for example, to force an option to the assembler, you
-would tell the driver (the dash before the E is
-required).
-
-
-
-Besides getting options to the Haskell compiler with ,
-you can get options through to its runtime system with
--optCrts<blah> option.
-
-
-
-So, for example: when I want to use my normal driver but with my
-profiled compiler binary, I use this script:
-
-
-#! /bin/sh
-exec /local/grasp_tmp3/simonpj/ghc-BUILDS/working-alpha/ghc/driver/ghc \
- -pgmC/local/grasp_tmp3/simonpj/ghc-BUILDS/working-hsc-prof/hsc \
- -optCrts-i0.5 \
- -optCrts-PT \
- "$@"
-
-
-
-
-
hunk ./ghc/docs/users_guide/debugging.sgml 78
-
-
-
-
-:
-
-
-Dump to the file "M.imports" (where M is the module being compiled)
-a "minimal" set of import declarations. You can safely replace
-all the import declarations in "M.hs" with those found in "M.imports".
-Why would you want to do that? Because the "minimal" imports (a) import
-everything explicitly, by name, and (b) import nothing that is not required.
-It can be quite painful to maintain this property by hand, so this flag is
-intended to reduce the labour.
-
-
-
-
-
-:
-
-
-Dump to stdout a summary of the differences between the existing interface file (if any)
-for this module, and the new one.
-
hunk ./ghc/docs/users_guide/flags.sgml 1
+
+ Flag reference
+
+
+ Help and verbosity options (<xref linkend="options-help">)
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+
+ help
+ static
+ -
+
+
+
+ help
+ static
+ -
+
+
+
+ verbose mode (equivalent to )
+ dynamic
+ -
+
+
+ n
+ set verbosity level
+ dynamic
+ -
+
+
+
+ display GHC version
+ static
+ -
+
+
+
+ display GHC version (numeric only)
+ static
+ -
+
+
+
+
+
+
+
+ Which phases to run (<xref linkend="options-order">)
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+
+ Run the C pre-processor on the Haskell source
+ dynamic
+ -
+
+
+
+ Stop after preprocessing (.hspp file)
+ static
+ -
+
+
+
+ Stop after generating C (.hc file)
+ static
+ -
+
+
+
+ Stop after generating assembly (.s file)
+ static
+ -
+
+
+
+ Stop after compiling to object code (.o file)
+ static
+ -
+
+
+
+ Use the native code generator
+ dynamic
+ -fvia-C
+
+
+
+ Compile via C
+ dynamic
+ -fasm
+
+
+
+
+
+
+
+ Redirecting output (<xref linkend="options-output">)
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+ suffix
+ set the suffix to use for interface files
+ static
+ -
+
+
+ filename
+ set output filename
+ static
+ -
+
+
+ dir
+ set output directory
+ static
+ -
+
+
+ filename
+ set the filename in which to put the interface
+ static
+
+
+
+ suffix
+ set the output file suffix
+ static
+ -
+
+
+
+
+
+
+
+ Keeping intermediate files (<xref linkend="keeping-intermediates">)
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+
+ retain intermediate .hc files
+ static
+ -
+
+
+
+ retain intermediate .s files
+ static
+ -
+
+
+
+ retain intermediate .raw_s files
+ static
+ -
+
+
+
+ retain all intermediate temporary files
+ static
+ -
+
+
+
+
+
+
+
+ Temporary files (<xref linkend="temp-files">)
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+
+ set the directory for temporary files
+ static
+ -
+
+
+
+
+
+
+
+ Finding imports (<xref linkend="options-finding-imports">)
+
+
+
+
+
+ Flag
+
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+ dir1:dir2:...
+ add dir,
+ dir2, etc. to import path
+ static
+ -
+
+
+
+ Empty the import directory list
+ static
+ -
+
+
+
+
+
+
+
+ Interface file options (<xref linkend="hi-options">)
+
+
+
+
+
+ Flag
+
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+ file
+ Put the interface file in file
+ static
+ -
+
+
+
+ Dump the new interface to stdout
+ dynamic
+ -
+
+
+
+ Show the differences vs. the old interface
+ dynamic
+ -
+
+
+
+
+
+
+
+ Recompilation checking (<xref linkend="recomp">)
+
+
+
+
+
+ Flag
+
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+
+ Turn off recompilation checking
+ static
+ -recomp
+
+
+
+
+
+
+
+ Packages (<xref linkend="packages">)
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+
+ Install a new package
+ static
+ -
+
+
+ name
+ Delete package entry name
+ static
+ -
+
+
+
+ List installed packages
+ static
+ -
+
+
+ name
+ Use package name
+ static
+ -
+
+
+ name
+ Compile code for package name
+ static
+ -
+
+
+
+
+
+
+
+ Language options (<xref linkend="options-language">)
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+
+
+ dynamic
+
+
+
+
+ Enable undecidable instances
+ dynamic
+
+
+
+
+ Enable generics
+ dynamic
+
+
+
+
+ Enable most language extensions
+ dynamic
+
+
+
+
+ Ignore assertions
+ dynamic
+
+
+
+
+ Don't implicitly import Prelude
+ dynamic
+ -
+
+
+
+ Disable the monomorphism restriction
+ dynamic
+
+
+
+
+ Make tuple pattern matching irrefutable
+ dynamic
+
+
+
+ n
+ set the limit for context reduction
+ dynamic
+
+
+
+
+
+
+
+
+ Warnings (<xref linkend="options-sanity">)
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+
+ enable normal warnings
+ static
+
+
+
+
+ disable all warnings
+ static
+ -
+
+
+
+ enable all warnings
+ static
+
+
+
+
+
+ warn about uses of functions & types that are deprecated
+ dynamic
+
+
+
+
+
+ warn when an entity is exported multiple times
+ dynamic
+
+
+
+
+
+ warn when a .hi file in the
+ current directory shadows a library
+ dynamic
+
+
+
+
+
+ warn when a pattern match could fail
+ dynamic
+
+
+
+
+
+ warn when fields of a record are uninitialised
+ dynamic
+
+
+
+
+
+ warn when class methods are undefined
+ dynamic
+
+
+
+
+
+ warn about top-level functions without signatures
+ dynamic
+
+
+
+
+
+ warn when names are shadowed
+ dynamic
+
+
+
+
+
+ warn about overlapping patterns
+ dynamic
+
+
+
+
+
+ warn about lambda-patterns that can fail
+ dynamic
+
+
+
+
+
+ warn when defaulting happens
+ dynamic
+
+
+
+
+
+ warn about bindings that are unused
+ dynamic
+
+
+
+
+
+ warn about unnecessary imports
+ dynamic
+
+
+
+
+
+ warn about variables in patterns that aren't used
+ dynamic
+
+
+
+
+
+
+
+
+
+ Optimisation levels (<xref linkend="options-optimise">)
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+
+ Enable default optimisation (level 1)
+ static
+
+
+
+ n
+ Set optimisation level n
+ static
+
+
+
+
+ Run gcc with
+ static
+ -
+
+
+
+
+
+
+
+ Individual optimisations (<xref linkend="options-f">)
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+
+ Make everything strict
+ dynamic
+
+
+
+
+
+ Enable case-merging
+ static
+
+
+
+
+
+ Make dictionaries strict
+ dynamic
+
+
+
+
+
+ Enable eta-reduction
+ static
+
+
+
+
+
+ Enable lambda eta-reduction
+ static
+
+
+
+
+
+ Enable excess intermediate precision
+ static
+
+
+
+
+
+ Enable foldr-build optimisation
+ static
+
+
+
+
+
+ Ignore assertions in the source
+ static
+
+
+
+
+
+ Ignore pragmas in interface files
+ static
+
+
+
+
+
+ Enable let-no-escape optimisation
+ static
+
+
+
+
+
+ Tweak the liberate-case optimisation
+ static
+
+
+
+
+
+ Don't generate interface pragmas
+ static
+
+
+
+
+
+ Set the max iterations for the simplifier
+ static
+ -
+
+
+
+
+ Turn off CPR analysis
+ static
+ -
+
+
+
+
+ Turn off common sub-expression
+ static
+ -
+
+
+
+
+ Turn off pre-inlining
+ static
+ -
+
+
+
+
+ Turn off strictness analysis
+ static
+ -
+
+
+
+
+ Make numbers strict
+ dynamic
+
+
+
+
+
+ Flatten strict constructor fields
+ static
+
+
+
+
+
+ Tweak unfolding settings
+ static
+
+
+
+
+
+ Tweak unfolding settings
+ static
+
+
+
+
+
+ Tweak unfolding settings
+ static
+
+
+
+
+
+ Tweak unfolding settings
+ static
+
+
+
+
+
+ Tweak unfolding settings
+ static
+
+
+
+
+
+ Tweak unfolding settings
+ static
+
+
+
+
+
+ Turn on UsageSP analysis
+ static
+
+
+
+
+
+
+
+
+ Profiling options (<xref linkend="profiling">)
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+
+ Auto-add _scc_s to all
+ exported functions
+ static
+
+
+
+
+ Auto-add _scc_s to all
+ top-level functions
+ static
+
+
+
+
+ Auto-add _scc_s to all dictionaries
+ static
+
+
+
+
+ Auto-add _scc_s to all CAFs
+ static
+
+
+
+
+ Turn on profiling
+ static
+ -
+
+
+
+ Turn on ticky-ticky profiling
+ static
+ -
+
+
+
+
+
+
+
+ Parallelism options (<xref linkend="sec-using-parallel">)
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+
+ Enable GRANSIM
+ static
+ -
+
+
+
+ Enable Parallel Haskell
+ static
+ -
+
+
+
+ Enable SMP support
+ static
+ -
+
+
+
+
+
+
+
+ C pre-processor options (<xref linkend="c-pre-processor">)
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+ symbol=value
+ Define a symbol in the C pre-processor
+ dynamic
+ symbol
+
+
+ symbol
+ Undefine a symbol in the C pre-processor
+ dynamic
+ -
+
+
+ dir
+ Add dir to the
+ directory search list for #include files
+ static
+ -
+
+
+
+
+
+
+
+ C compiler options (<xref linkend="options-C-compiler">)
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+ file
+ Include file when
+ compiling the .hc file
+ dynamic
+ -
+
+
+
+
+
+
+
+ Linking options (<xref linkend="options-linker">)
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+
+ Use dynamic Haskell libraries (if available)
+ static
+ -
+
+
+ lib
+ Link in library lib
+ static
+ -
+
+
+ dir
+ Add dir to the list of
+ directories searched for libraries
+ static
+ -
+
+
+ name
+ Link in package name
+ static
+ -
+
+
+
+ Split objects (for libraries)
+ static
+ -
+
+
+
+ Use static Haskell libraries
+ static
+ -
+
+
+
+ Don't asssume this program contains main
+ static
+ -
+
+
+
+
+
+
+
+ Replacing phases (<xref linkend="replacing-phases">)
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+ cmd
+ Use cmd as the literate pre-processor
+ static
+ -
+
+
+ cmd
+ Use cmd as the C
+ pre-processor (with only)
+ static-
+
+
+ cmd
+ Use cmd as the C compiler
+ static
+ -
+
+
+ cmd
+ Use cmd as the assembler
+ static
+ -
+
+
+ cmd
+ Use cmd as the linker
+ static
+ -
+
+
+ cmd
+ Use cmd as the DLL generator
+ static
+ -
+
+
+ cmd
+ Use cmd as the dependency generator
+ static
+ -
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Forcing options to particular phases (<xref linkend="forcing-options-through">)
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+ option
+ pass option to the literate pre-processor
+ dynamic
+ -
+
+
+ option
+ pass option to cpp (with
+ only)
+ dynamic
+ -
+
+
+ option
+ pass option to the C compiler
+ dynamic
+ -
+
+
+ option
+ pass option to the assembler
+ dynamic
+ -
+
+
+ option
+ pass option to the linker
+ static
+ -
+
+
+ option
+ pass option to the DLL generator
+ static
+ -
+
+
+ option
+ pass option to the dependency generator
+ static
+ -
+
+
+
+
+
+
+
+ Platform-specific options (<xref linkend="options-platform">)
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+
+ (SPARC only) enable version 8 support
+ static
+ -
+
+
+
+ (HPPA only) enable long call support
+ static
+ -
+
+
+
+ (x86 only) give some registers back to the C compiler
+ dynamic
+ -
+
+
+
+
+
+
+
+ Compiler debugging options (<xref linkend="options-debugging">)
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+
+ Turn on internal sanity checking
+ dynamic
+ -
+
+
+
+ Dump abstract C
+ dynamic
+ -
+
+
+
+ Dump assembly
+ dynamic
+ -
+
+
+
+ Dump interpreter byte code
+ dynamic
+ -
+
+
+
+ Dump output from CPR analysis
+ dynamic
+ -
+
+
+
+ Dump CSE output
+ dynamic
+ -
+
+
+
+ Dump deriving output
+ dynamic
+ -
+
+
+
+ Dump desugarer output
+ dynamic
+ -
+
+
+
+ Dump “flat” C
+ dynamic
+ -
+
+
+
+ Dump FFI-related output
+ dynamic
+ -
+
+
+
+ Dump inlining info
+ dynamic
+ -
+
+
+
+ Dump occurrence analysis output
+ dynamic
+ -
+
+
+
+ Dump parse tree
+ dynamic
+ -
+
+
+
+ Dump “real” C
+ dynamic
+ -
+
+
+
+ Dump renamer output
+ dynamic
+ -
+
+
+
+ Dump rules
+ dynamic
+ -
+
+
+
+ Dump saturated output
+ dynamic
+ -
+
+
+
+ Dump final simplifier output
+ dynamic
+ -
+
+
+
+ Dump output from each simplifier iteration
+ dynamic
+ -
+
+
+
+ Dump specialiser output
+ dynamic
+ -
+
+
+
+ Dump final STG
+ dynamic
+ -
+
+
+
+ Dump strictness analyser output
+ dynamic
+ -
+
+
+
+ Dump typechecker output
+ dynamic
+ -
+
+
+
+ Dump type signatures
+ dynamic
+ -
+
+
+
+ Dump UsageSP analysis output
+ dynamic
+ -
+
+
+
+ Dump worker-wrapper output
+ dynamic
+ -
+
+
+
+ (equivalent to )
+ dynamic
+ -
+
+
+
+ Trace renamer
+ dynamic
+ -
+
+
+
+ Renamer stats
+ dynamic
+ -
+
+
+
+ Native code generator intermediate form
+ dynamic
+ -
+
+
+
+ Dump simplifier stats
+ dynamic
+ -
+
+
+
+ Turn on debug printing (more verbose)
+ static
+ -
+
+
+
+ Don't output pragma info in dumps
+ static
+ -
+
+
+
+ Set the depth for printing expressions in error msgs
+ static
+ -
+
+
+
+ Dump haskell source stats
+ dynamic
+ -
+
+
+
+ STG pass sanity checking
+ dynamic
+ -
+
+
+
+ Dump STG stats
+ dynamic
+ -
+
+
+
+ UsageSP sanity checker
+ dynamic
+ -
+
+
+
+ Show output from each core-to-core pass
+ dynamic
+ -
+
+
+
+ Show output from each STG-to-STG pass
+ dynamic
+ -
+
+
+
+
+
+
+
+ Misc compiler options
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+
+ Allow casms in unfoldings
+ static
+ -
+
+
+
+ ???
+ static
+ -
+
+
+
+ Make all top-level names global (for )
+ static
+ -
+
+
+
+ Don't complain about .hi file mismatches
+ static
+ -
+
+
+
+ Turn off black holing (probably doesn't work)
+ static
+ -
+
+
+
+ ???
+ static
+ -
+
+
+
+ Renamer: don't prune declarations
+ static
+ -
+
+
+
+ Renamer: don't prune type declarations
+ static
+ -
+
+
+
+ Set simplification history size
+ static
+ -
+
+
+
+ Unregisterised compilation (use instead)
+ static
+ -
+
+
+
+ Turn off assembly mangling (use instead)
+ static
+ -
+
+
+
+
+
+
+
+
+
+
+
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 142
-
-Language variations
-
+
+ Language options
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 145
- There are several flags that control what variation of the language are permitted.
-Leaving out all of them gives you standard Haskell 98.
+ languageoption
+
+ optionslanguage
+
+ extensionsoptions controlling
+
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 152
-
+ These flags control what variation of the language are
+ permitted. Leaving out all of them gives you standard Haskell
+ 98.
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 156
-
-:
-
-This simultaneously enables all of the extensions to Haskell 98 described in this
-chapter, except where otherwise noted.
-
+
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 158
-
-:
-
- Switch off the Haskell 98 monomorphism restriction. Independent of the
-flag.
-
+
+ :
+
+
+ This simultaneously enables all of the extensions to
+ Haskell 98 described in , except where otherwise
+ noted.
+
+
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 169
-
-,
- ,
- :
-
- See .
-Only relevant if you also use .
-
-
+
+ :
+
+
+ Switch off the Haskell 98 monomorphism restriction.
+ Independent of the
+ flag.
+
+
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 179
-
-:
-
- See .
-Only relevant if you also use .
-
-
+
+
+
+
+
+
+
+
+ See . Only relevant
+ if you also use .
+
+
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 192
-
- :
-
- See .
-Only relevant if you also use .
-
+
+ :
+
+
+ See . Only relevant if
+ you also use .
+
+
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 201
-
- :
-
- See .
-Independent of .
-
-
+
+
+
+
+ See . Only relevant if
+ you also use .
+
+
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 210
-
+
+
+
+
+ See . Independent of
+ .
+
+
+
+
+
+
+ -fno-implicit-prelude
+ option GHC normally imports
+ Prelude.hi files for you. If you'd
+ rather it didn't, then give it a
+ option. The idea
+ is that you can then import a Prelude of your own. (But
+ don't call it Prelude; the Haskell
+ module namespace is flat, and you must not conflict with
+ any Prelude module.)
+
+ Even though you have not imported the Prelude, all
+ the built-in syntax still refers to the built-in Haskell
+ Prelude types and values, as specified by the Haskell
+ Report. For example, the type [Int]
+ still means Prelude.[] Int; tuples
+ continue to refer to the standard Prelude tuples; the
+ translation for list comprehensions continues to use
+ Prelude.map etc.
+
+ With one group of exceptions! You may want to
+ define your own numeric class hierarchy. It completely
+ defeats that purpose if the literal "1" means
+ "Prelude.fromInteger 1", which is what
+ the Haskell Report specifies. So the
+ flag causes the
+ following pieces of built-in syntax to refer to whatever
+ is in scope, not the Prelude versions:
+
+
+
+ Integer and fractional literals mean
+ "fromInteger 1" and
+ "fromRational 3.2", not the
+ Prelude-qualified versions; both in expressions and in
+ patterns.
+
+
+
+ Negation (e.g. "- (f x)")
+ means "negate (f x)" (not
+ Prelude.negate).
+
+
+
+ In an n+k pattern, the standard Prelude
+ Ord class is used for comparison,
+ but the necessary subtraction uses whatever
+ "(-)" is in scope (not
+ "Prelude.(-)").
+
+
+
+
+
+
+
hunk ./ghc/docs/users_guide/packages.sgml 1
+
+ Packages
+ packages
+
+ Packages are collections of libraries, conveniently grouped
+ together as a single entity. The package system is flexible: a
+ package may consist of Haskell code, foreign language code (eg. C
+ libraries), or a mixture of the two. A package is a good way to
+ group together related Haskell modules, and is essential if you
+ intend to make the modules into a Windows DLL (see below).
+
+ Because packages can contain both Haskell and C libraries, they
+ are also a good way to provide convenient access to a Haskell
+ layer over a C library.
+
+ GHC comes with several packages (see ), and packages can be added/removed from an
+ existing GHC installation.
+
+
+ Listing the available packages
+ packages
+ listing
+
+ To see what packages are currently installed, use the
+ --list-packages option:
+ --list-packages
+
+
+
+ $ ghc --list-packages
+ gmp, rts, std, lang, concurrent, data, net, posix, text, util
+
+
+ Note that your GHC installation might have a slightly
+ different set of packages installed.
+
+ The gmp and rts
+ packages are always present, and represent the multi-precision
+ integer and runtime system libraries respectively. The
+ std package contains the Haskell prelude.
+ The rest of the packages are optional libraries.
+
+
+
+
+ Using a package
+ packages
+ using
+
+ To use a package, add the -package flag
+ to the command line:
+
+
+
+
+ -package <lib> option
+
+ This option brings into scope all the modules from
+ package <lib> (they still have to
+ be imported in your Haskell source, however). It also
+ causes the relevant libraries to be linked when linking is
+ being done.
+
+
+
+
+ Some packages depend on other packages, for example the
+ text package makes use of some of the modules
+ in the lang package. The package system
+ takes care of all these dependencies, so that when you say
+ -package text on the command line, you
+ automatically get -package lang too.
+
+
+
+ Building a package from Haskell source
+ packages
+ building
+
+ It takes some special considerations to build a new
+ package:
+
+
+
+ A package may contain several Haskell modules. A
+ package may span many directories, or many packages may
+ exist in a single directory. Packages may not be mutually
+ recursive.
+
+
+
+ A package has a name
+ (e.g. std)
+
+
+
+ The Haskell code in a package may be built into one or
+ more Unix libraries (e.g. libHSfoo.a),
+ or a single DLL on Windows
+ (e.g. HSfoo.dll). The restriction to a
+ single DLL on Windows is that the package system is used to
+ tell the compiler when it should make an inter-DLL call
+ rather than an intra-DLL call (inter-DLL calls require an
+ extra indirection).
+
+
+
+ GHC does not maintain detailed cross-package
+ dependency information. It does remember which modules in
+ other packages the current module depends on, but not which
+ things within those imported things.
+
+
+
+ To compile a module which is to be part of a new package,
+ use the -package-name option:
+
+
+
+
+ -package-name
+ option
+
+ This option is added to the command line when
+ compiling a module that is destined to be part of package
+ foo. If this flag is omitted then the
+ default package Main is assumed.
+
+
+
+
+ Failure to use the -package-name option
+ when compiling a package will result in disaster on Windows, but
+ is relatively harmless on Unix at the moment (it will just cause
+ a few extra dependencies in some interface files). However,
+ bear in mind that we might add support for Unix shared libraries
+ at some point in the future.
+
+ It is worth noting that on Windows, because each package
+ is built as a DLL, and a reference to a DLL costs an extra
+ indirection, intra-package references are cheaper than
+ inter-package references. Of course, this applies to the
+ Main package as well.
+
+
+
+ Package management
+ packages
+ management
+
+ GHC uses a package configuration file, called
+ packages.conf, which can be found in your GHC
+ install directory. This file isn't intended to be edited
+ directly, instead GHC provides options for adding & removing
+ packages:
+
+
+
+
+ --add-package
+ option
+
+ Reads a package specification (see below) on stdin,
+ and adds it to the database of installed packages. The
+ package specification must be a package that isn't already
+ installed.
+
+
+
+
+
+ --delete-package
+ option
+
+ Removes the specified package from the installed
+ configuration.
+
+
+
+
+ In both cases, the old package configuration file is saved
+ in packages.conf.old in your GHC install
+ directory, so in an emergency you can always copy this file into
+ package.conf to restore the old
+ settings.
+
+ A package specification looks like this:
+
+
+ Package {
+ name = "mypkg",
+ import_dirs = ["/usr/local/lib/imports/mypkg"],
+ library_dirs = ["/usr/local/lib"],
+ hs_libraries = ["HSmypkg" ],
+ extra_libraries = ["HSmypkg_cbits"],
+ include_dirs = [],
+ c_includes = ["HsMyPkg.h"],
+ package_deps = ["text", "data"],
+ extra_ghc_opts = [],
+ extra_cc_opts = [],
+ extra_ld_opts = ["-lmy_clib"]
+ }
+
+
+ Components of a package specification may be specified in
+ any order, and are:
+
+
+
+ name
+ name
+ package specification
+
+ The package's name, for use with
+ the -package flag and as listed in the
+ --list-packages list.
+
+
+
+
+
+ import_dirs
+ import_dirs
+ package specification
+
+ A list of directories containing interface files
+ (.hi files) for this package.
+
+
+
+
+ library_dirs
+ library_dirs
+ package specification
+
+ A list of directories containing libraries for this
+ package.
+
+
+
+
+ hs_libraries
+ hs_libraries
+ package specification
+
+ A list of libraries containing Haskell code for this
+ package, with the .a or
+ .dll suffix omitted. On Unix, the
+ lib prefix is also omitted.
+
+
+
+
+ extra_libraries
+ extra_libraries
+ package specification
+
+ A list of extra libraries for this package. The
+ difference between hs_libraries and
+ extra_libraries is that
+ hs_libraries normally have several
+ versions, to support profiling, parallel and other build
+ options. The various versions are given different
+ suffixes to distinguish them, for example the profiling
+ version of the standard prelude library is named
+ libHSstd_p.a, with the
+ _p indicating that this is a profiling
+ version. The suffix is added automatically by GHC for
+ hs_libraries only, no suffix is added
+ for libraries in
+ extra_libraries.
+
+ Also, extra_libraries are placed
+ on the linker command line before the
+ hs_libraries for the same package. If
+ your package has dependencies in the other direction, you
+ might need to make two separate packages.
+
+
+
+
+ include_dirs
+ include_dirs
+ package specification
+
+ A list of directories containing C includes for this
+ package (maybe the empty list).
+
+
+
+
+ c_includes
+ c_includes
+ package specification
+
+ A list of files to include for via-C compilations
+ using this package. Typically this include file will
+ contain function prototypes for any C functions used in
+ the package, in case they end up being called as a result
+ of Haskell functions from the package being
+ inlined.
+
+
+
+
+ package_deps
+ package_deps
+ package specification
+
+ A list of packages which this package depends
+ on.
+
+
+
+
+ extra_ghc_opts
+ extra_ghc_opts
+ package specification
+
+ Extra arguments to be added to the GHC command line
+ when this package is being used.
+
+
+
+
+ extra_cc_opts
+ extra_cc_opts
+ package specification
+
+ Extra arguments to be added to the gcc command line
+ when this package is being used (only for via-C
+ compilations).
+
+
+
+
+ extra_ld_opts
+ extra_ld_opts
+ package specification
+
+ Extra arguments to be added to the gcc command line
+ (for linking) when this package is being used.
+
+
+
+
+ For examples of more package specifications, take a look
+ at the package.conf in your GHC
+ installation.
+
+
+
+
hunk ./ghc/docs/users_guide/phases.sgml 1
+
+ Options related to a particular phase
+
+
+ Replacing the program for one or more phases.
+ phases, changing
+
+ You may specify that a different program be used for one
+ of the phases of the compilation system, in place of whatever
+ the ghc has wired into it. For example, you
+ might want to try a different assembler. The following options
+ allow you to change the external program used for a given
+ compilation phases:
+
+
+
+
+ Forcing options to a particular phase.
+ forcing GHC-phase options
+
+ Options can be forced through to a particlar compilation
+ phase, using the following flags:
+
+
+ So, for example, to force an
+ option to the assembler, you would tell the driver
+ (the dash before the E is
+ required).
+
+ GHC is itself a Haskell program, so if you need to pass
+ options directly to GHC's runtime system you can enclose them in
+ +RTS ... -RTS (see ).
+
+
+
+
+ Options affecting the C pre-processor
+
+ pre-processing: cpp
+ C pre-processor options
+ cpp, pre-processing with
+
+ The C pre-processor cpp is run over
+ your Haskell code only if the option
+ -cpp option is given.
+ Unless you are building a large system with significant doses of
+ conditional compilation, you really shouldn't need it.
+
+
+
+
+ symbol=value
+
+
+ Define macro symbol in the
+ usual way. NB: does not affect
+ macros passed to the C compiler
+ when compiling via C! For those, use the
+ hack… (see ).
+
+
+
+
+ symbol
+
+
+ Undefine macro symbol in the
+ usual way.
+
+
+
+
+ dir
+
+
+ Specify a directory in which to look for
+ #include files, in the usual C
+ way.
+
+
+
+
+ The GHC driver pre-defines several macros when processing
+ Haskell source code (.hs or
+ .lhs files):
+
+
+
+
+ __HASKELL98__
+ __HASKELL98__
+
+ If defined, this means that GHC supports the
+ language defined by the Haskell 98 report.
+
+
+
+
+ __HASKELL__=98
+ __HASKELL__=98
+
+ In GHC 4.04 and later, the
+ __HASKELL__
+ macro is defined as having the value
+ 98.
+
+
+
+
+ __HASKELL1__
+ __HASKELL1__
+
+
+ If defined to n, that
+ means GHC supports the Haskell language defined in the
+ Haskell report version 1.n.
+ Currently 5. This macro is deprecated, and will probably
+ disappear in future versions.
+
+
+
+
+ __GLASGOW_HASKELL__
+ __GLASGOW_HASKELL__
+
+ For version n of the GHC
+ system, this will be #defined to
+ 100n. For example, for version
+ 5.00, it is 500.
+
+ With any luck,
+ __GLASGOW_HASKELL__
+ will be undefined in all other implementations that
+ support C-style pre-processing.
+
+ (For reference: the comparable symbols for other
+ systems are:
+ __HUGS__
+ for Hugs and
+ __HBC__
+ for Chalmers.)
+
+ NB. This macro is set when pre-processing both
+ Haskell source and C source, including the C source
+ generated from a Haskell module
+ (i.e. .hs, .lhs,
+ .c and .hc
+ files).
+
+
+
+
+ __CONCURRENT_HASKELL__
+ __CONCURRENT_HASKELL__
+
+ This symbol is defined when pre-processing Haskell
+ (input) and pre-processing C (GHC output). Since GHC from
+ verion 4.00 now supports concurrent haskell by default,
+ this symbol is always defined.
+
+
+
+
+ __PARALLEL_HASKELL__
+ __PARALLEL_HASKELL__
+
+ Only defined when is in
+ use! This symbol is defined when pre-processing Haskell
+ (input) and pre-processing C (GHC output).
+
+
+
+
+ A small word of warning: is not
+ friendly to “string gaps”.-cpp
+ vs string gapsstring
+ gaps vs -cpp. In other words, strings
+ such as the following:
+
+
+strmod = "\
+\ p \
+\ "
+
+
+ don't work with ;
+ /usr/bin/cpp elides the backslash-newline
+ pairs.
+
+ However, it appears that if you add a space at the end of
+ the line, then cpp (at least GNU
+ cpp and possibly other
+ cpps) leaves the backslash-space pairs alone
+ and the string gap works as expected.
+
+
+
+ Options affecting the C compiler (if applicable)
+
+ include-file options
+ C compiler options
+ GCC options
+
+
+
+
+
+ Flag
+ Description
+ Static/Dynamic
+ Reverse
+
+
+
+
+ file
+ Include file when
+ compiling the .hc file
+ dynamic
+ -
+
+
+
+
+
+ If you are compiling with lots of foreign calls, you may
+ need to tell the C compiler about some
+ #include files. There is no real pretty
+ way to do this, but you can use this hack from the
+ command-line:
+
+
+% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
+
+
+
+
+
+ Options affecting linking
+
+ linker options
+ ld options
+
+
+ GHC has to link your code with various libraries, possibly
+ including: user-supplied, GHC-supplied, and system-supplied
+ ( math library, for example).
+
+
+
+
+ lib
+
+
+ Link in the lib library.
+ On Unix systems, this will be in a file called
+ liblib.a
+ or
+ liblib.so
+ which resides somewhere on the library directories path.
+
+ Because of the sad state of most UNIX linkers, the
+ order of such options does matter. If library
+ foo requires library
+ bar, then in general
+ foo should
+ come before
+ bar on the
+ command line.
+
+
+
+
+ name
+
+
+ If you are using a Haskell “package”
+ (see ), don't forget to add the
+ relevant option when linking the
+ program too: it will cause the appropriate libraries to be
+ linked in with the program. Forgetting the
+ option will likely result in
+ several pages of link errors.
+
+
+
+
+ dir
+
+
+ Where to find user-supplied libraries…
+ Prepend the directory dir to
+ the library directories path.
+
+
+
+
+
+
+
+ Tell the linker to split the single object file that
+ would normally be generated into multiple object files,
+ one per top-level Haskell function or type in the module.
+ We use this feature for building GHC's libraries libraries
+ (warning: don't use it unless you know what you're
+ doing!).
+
+
+
+
+
+
+
+ Tell the linker to avoid shared Haskell libraries,
+ if possible. This is the default.
+
+
+
+
+
+
+
+ Tell the linker to use shared Haskell libraries, if
+ available (this option is only supported on Windows at the
+ moment, and also note that your distribution of GHC may
+ not have been supplied with shared libraries).
+
+
+
+
+
+
+ linking Haskell libraries with foreign code
+
+ In the event you want to include ghc-compiled code
+ as part of another (non-Haskell) program, the RTS will not
+ be supplying its definition of main()
+ at link-time, you will have to. To signal that to the
+ driver script when linking, use
+ .
+
+ Notice that since the command-line passed to the
+ linker is rather involved, you probably want to use
+ ghc to do the final link of your
+ `mixed-language' application. This is not a requirement
+ though, just try linking once with on
+ to see what options the driver passes through to the
+ linker.
+
+
+
+
+
+
+
+
hunk ./ghc/docs/users_guide/separate_compilation.sgml 1
+
+ Separate compilation
+
+ separate compilation
+ recompilation checker
+ make and recompilation
+
+ This section describes how GHC supports separate
+ compilation.
+
+
+ Interface files
+
+ interface files
+ .hi files
+
+ When GHC compiles a source file A.hs
+ 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.
+
+ 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
+ module Main, which can be placed in any
+ file.filenamesfor
+ modules
+
+ The interface file for A contains
+ information needed by the compiler when it compiles any module
+ B that imports A, whether
+ directly or indirectly. When compiling B,
+ GHC will read A.hi to find the details that
+ it needs to know about things defined in
+ A.
+
+ The interface file may contain all sorts of things that
+ aren't explicitly exported from A by the
+ programmer. For example, even though a data type is exported
+ abstractly, A.hi will contain the full data
+ type definition. For small function definitions,
+ A.hi will contain the complete definition
+ of the function. For bigger functions,
+ A.hi will contain strictness information
+ about the function. And so on. GHC puts much more information
+ into .hi files when optimisation is turned
+ on with the flag (see ). Without it
+ puts in just the minimum; with it lobs in a
+ whole pile of stuff. optimsation, effect on
+ .hi files
+
+ A.hi should really be thought of as a
+ compiler-readable version of A.o. If you
+ use a .hi file that wasn't generated by the
+ same compilation run that generates the .o
+ file the compiler may assume all sorts of incorrect things about
+ A, resulting in core dumps and other
+ unpleasant happenings.
+
+
+
+
+ Finding interface files
+
+ interface files, finding them
+ finding interface files
+
+ In your program, you import a module
+ Foo by saying import Foo.
+ GHC goes looking for an interface file,
+ Foo.hi. It has a builtin list of
+ directories (notably including .) where it
+ looks.
+
+
+
+
+
+
+
+ This flag prepends a colon-separated
+ list of dirs to the “import
+ directories” list. See also
+ for the significance of using relative and absolute
+ pathnames in the list.
+
+
+
+
+
+
+ resets the “import directories” list
+ back to nothing.
+
+
+
+
+
+ See also the section on packages (), which describes how to use installed
+ libraries.
+
+
+
+
+ Other options related to interface files
+ interface files, options
+
+
+
+ file
+
+
+
+ The interface output may be directed to another file
+ bar2/Wurble.iface with the option
+ (not recommended).
+ To avoid generating an interface at all, you can say
+ -ohi /dev/null, for example.
+
+
+
+
+
+
+
+
+ Dumps the new interface to standard output.
+
+
+
+
+
+
+
+
+ The compiler does not overwrite an existing
+ .hi interface file if the new one is
+ the same as the old one; this is friendly to
+ make. When an interface does change,
+ it is often enlightening to be informed. The
+ option will make GHC run
+ diff on the old and new
+ .hi files.
+
+
+
+
+
+
+
+
+ Dump to the file "M.imports" (where M is the module
+ being compiled) a "minimal" set of import declarations.
+ You can safely replace all the import declarations in
+ "M.hs" with those found in "M.imports". Why would you
+ want to do that? Because the "minimal" imports (a) import
+ everything explicitly, by name, and (b) import nothing
+ that is not required. It can be quite painful to maintain
+ this property by hand, so this flag is intended to reduce
+ the labour.
+
+
+
+
+
+
+
+ The recompilation checker
+
+ recompilation checker
+
+
+
+
+
+
+
+ Turn off recompilation checking (which is on by
+ default). Recompilation checking normally stops
+ compilation early, leaving an existing
+ .o file in place, if it can be
+ determined that the module does not need to be
+ recompiled.
+
+
+
+
+ In the olden days, GHC compared the newly-generated
+ .hi file with the previous version; if they
+ were identical, it left the old one alone and didn't change its
+ modification date. In consequence, importers of a module with
+ an unchanged output .hi file were not
+ recompiled.
+
+ This doesn't work any more. Suppose module
+ C imports module B, and
+ B imports module A. So
+ changes to A.hi should force a
+ recompilation of C. And some changes to
+ A (changing the definition of a function that
+ appears in an inlining of a function exported by
+ B, say) may conceivably not change
+ B.hi one jot. So now…
+
+ GHC keeps a version number on each interface file, and on
+ each type signature within the interface file. It also keeps in
+ every interface file a list of the version numbers of everything
+ it used when it last compiled the file. If the source file's
+ modification date is earlier than the .o
+ file's date (i.e. the source hasn't changed since the file was
+ last compiled), and the reompilation checking is on, GHC will be
+ clever. It compares the version numbers on the things it needs
+ this time with the version numbers on the things it needed last
+ time (gleaned from the interface file of the module being
+ compiled); if they are all the same it stops compiling rather
+ early in the process saying “Compilation IS NOT
+ 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
+ copy.
+
+
+
+
+ Using <command>make</command>
+
+ make
+
+ It is reasonably straightforward to set up a
+ 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)
+
+SRCS = Main.lhs Foo.lhs Bar.lhs
+OBJS = Main.o Foo.o Bar.o
+
+.SUFFIXES : .o .hs .hi .lhs .hc .s
+
+cool_pgm : $(OBJS)
+ rm $@
+ $(HC) -o $@ $(HC_OPTS) $(OBJS)
+
+# Standard suffix rules
+.o.hi:
+ @:
+
+.lhs.o:
+ $(HC) -c $< $(HC_OPTS)
+
+.hs.o:
+ $(HC) -c $< $(HC_OPTS)
+
+# 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.)
+
+ Note the cheesy .o.hi rule: It records
+ the dependency of the interface (.hi) file
+ on the source. The rule says a .hi file
+ can be made from a .o file by
+ doing…nothing. Which is true.
+
+ 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
+ Foo.s have an earlier modification date than
+ Baz.hi, then the out-of-date file must be
+ brought up to date. To bring it up to date,
+ make looks for a rule to do so; one of the
+ preceding suffix rules does the job nicely.
+
+
+ Dependency generation
+ dependencies in Makefiles
+ Makefile dependencies
+
+ Putting inter-dependencies of the form Foo.o :
+ Bar.hi into your Makefile by
+ hand is rather error-prone. Don't worry, GHC has support for
+ 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
+ make depend before you do make
+ cool_pgm. ghc -M will
+ append the needed dependencies to your
+ Makefile.
+
+ In general, if module A contains the
+ line
+
+
+import B ...blah...
+
+
+ then ghc -M will generate a dependency line
+ of the form:
+
+
+A.o : B.hi
+
+
+ If module A contains the line
+
+
+import {-# SOURCE #-} B ...blah...
+
+
+ then ghc -M will generate a dependency
+ line of the form:
+
+
+A.o : B.hi-boot
+
+
+ (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
+ target.
+
+ By default, ghc -M generates all the
+ dependencies, and then concatenates them onto the end of
+ makefile (or
+ Makefile if makefile
+ doesn't exist) bracketed by the lines "# DO NOT
+ DELETE: Beginning of Haskell dependencies" and
+ "# DO NOT DELETE: End of Haskell
+ dependencies". If these lines already exist in the
+ makefile, then the old dependencies are
+ deleted first.
+
+ The dependency generation phase of GHC can take some
+ additional options, which you may find useful. For historical
+ reasons, each option passed to the dependency generator from
+ the GHC command line must be preceded by
+ -optdep. For example, to pass -f
+ .depend to the dependency generator, you say
+
+
+ghc -M -optdep-f -optdep.depend ...
+
+
+ The options which affect dependency generation are:
+
+
+
+
+
+ Turn off warnings about interface file shadowing.
+
+
+
+
+ file
+
+ Use file as the makefile,
+ rather than makefile or
+ Makefile. If
+ file doesn't exist,
+ mkdependHS creates it. We often use
+ to put the dependencies in
+ .depend and then
+ include the file
+ .depend into
+ Makefile.
+
+
+
+
+
+
+ Use .<osuf> as the
+ "target file" suffix ( default: o).
+ Multiple flags are permitted
+ (GHC2.05 onwards). Thus ""
+ will generate dependencies for .hc
+ and .o files.
+
+
+
+
+
+
+ Make extra dependencies that declare that files
+ with suffix
+ .<suf>_<osuf>
+ depend on interface files with suffix
+ .<suf>_hi, or (for
+ {-# SOURCE #-}
+ imports) on .hi-boot. Multiple
+ flags are permitted. For example,
+ will make dependencies
+ for .hc on
+ .hi,
+ .a_hc on
+ .a_hi, and
+ .b_hc on
+ .b_hi. (Useful in
+ conjunction with NoFib "ways".)
+
+
+
+
+
+
+ Regard <file> as
+ "stable"; i.e., exclude it from having dependencies on
+ it.
+
+
+
+
+
+
+ same as
+
+
+
+
+
+
+ Regard the colon-separated list of directories
+ <dirs> as containing stable,
+ don't generate any dependencies on modules
+ therein.
+
+
+
+
+
+
+ Regard <file> as not
+ "stable"; i.e., generate dependencies on it (if
+ any). This option is normally used in conjunction with
+ the option.
+
+
+
+
+
+
+ Regard prelude libraries as unstable, i.e.,
+ generate dependencies on the prelude modules used
+ (including Prelude). This option is
+ normally only used by the various system libraries. If a
+ option is used, dependencies
+ will also be generated on the library's
+ interfaces.
+
+
+
+
+
+
+
+
+ How to compile mutually recursive modules
+
+ module system, recursion
+ recursion, between modules
+
+ Currently, the compiler does not have proper support for
+ dealing with mutually recursive modules:
+
+
+module A where
+
+import B
+
+newtype TA = MkTA Int
+
+f :: TB -> TA
+f (MkTB x) = MkTA x
+--------
+module B where
+
+import A
+
+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,
+ to get mutually recursive modules off the ground, you need to
+ hand write an interface file for A or B, so as to break the
+ loop. These hand-written interface files are called
+ hi-boot files, and are placed in a file
+ called <module>.hi-boot. To import
+ from an hi-boot file instead of the standard
+ .hi file, use the following syntax in the
+ importing module: hi-boot
+ filesimporting,
+ hi-boot files
+
+
+import {-# SOURCE #-} A
+
+
+ The hand-written interface need only contain the bare
+ minimum of information needed to get the bootstrapping process
+ 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.
+
+ For the example at hand, the boot interface file for A
+ would look like the following:
+
+
+__interface A 1 0 where
+__export A TA{MkTA} ;
+1 newtype TA = MkTA PrelBase.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.
+
+ 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
+
+
+ (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.
+
+
+
+
hunk ./ghc/docs/users_guide/ug-ent.sgml 1
+
hunk ./ghc/docs/users_guide/ug-ent.sgml 13
+
hunk ./ghc/docs/users_guide/ug-ent.sgml 15
+
+
hunk ./ghc/docs/users_guide/using.sgml 2
-Using GHC
-
+Using GHC
+
hunk ./ghc/docs/users_guide/using.sgml 11
-using the make tool (this is especially useful if the program
+using the make tool (this is especially useful if the program
hunk ./ghc/docs/users_guide/using.sgml 17
-Overall command-line structure
-
+Overall command-line structure
+
hunk ./ghc/docs/users_guide/using.sgml 42
-Command-line options begin with -. They may not be
+Command-line options begin with -. They may not be
hunk ./ghc/docs/users_guide/using.sgml 44
-precede filenames: e.g., ghc *.o -o foo. All options are
+precede filenames: e.g., ghc *.o -o foo. All options are
hunk ./ghc/docs/users_guide/using.sgml 46
-ghc -c -O1 Foo.hs -O2 Bar.hs to apply different optimisation
-levels to the files Foo.hs and Bar.hs. For conflicting
+ghc -c -O1 Foo.hs -O2 Bar.hs to apply different optimisation
+levels to the files Foo.hs and Bar.hs. For conflicting
hunk ./ghc/docs/users_guide/using.sgml 55
-Meaningful file suffixes
-
+Meaningful file suffixes
+
hunk ./ghc/docs/users_guide/using.sgml 64
-File names with “meaningful” suffixes (e.g., .lhs or .o)
+File names with “meaningful” suffixes (e.g., .lhs or .o)
hunk ./ghc/docs/users_guide/using.sgml 72
-.lhs:
+.lhs:
hunk ./ghc/docs/users_guide/using.sgml 81
-.hs:
+.hs:
hunk ./ghc/docs/users_guide/using.sgml 89
-.hi:
+.hi:
hunk ./ghc/docs/users_guide/using.sgml 97
-.hc:
+.hc:
hunk ./ghc/docs/users_guide/using.sgml 105
-.c:
+.c:
hunk ./ghc/docs/users_guide/using.sgml 113
-.s:
+.s:
hunk ./ghc/docs/users_guide/using.sgml 122
-.o:
+.o:
hunk ./ghc/docs/users_guide/using.sgml 139
-
-Help and verbosity options
-
-
-
-help options (GHC)
-verbose option (GHC)
-
-
-
-
-
-
- Flag
- Description
- Static/Dynamic
- Reverse
-
-
-
-
- -?
- help
- static
- -
-
-
- -help
- help
- static
- -
-
-
- -v
- verbose mode (equivalent to -v3)
- dynamic
- -
-
-
- -vn
- set verbosity level
- dynamic
- -
-
-
- --version
- display GHC version
- static
- -
-
-
- --numeric-version
- display GHC version (numeric only)
- static
- -
-
-
-
-
+
+ Help and verbosity options
hunk ./ghc/docs/users_guide/using.sgml 142
+ help options
+ verbosity options
hunk ./ghc/docs/users_guide/using.sgml 162
- verbose: it reports its version number
+ verbose: it reports its version number
hunk ./ghc/docs/users_guide/using.sgml 176
- -vn
- -vn
+ -vn
+
hunk ./ghc/docs/users_guide/using.sgml 259
-
-
-
-
- Flag
- Description
- Static/Dynamic
- Reverse
-
-
-
-
- -cpp
- Run the C pre-processor on the Haskell source
- dynamic
- -
-
-
- -E
- Stop after preprocessing (.hspp file)
- static
- -
-
-
- -C
- Stop after generating C (.hc file)
- static
- -
-
-
- -S
- Stop after generating assembly (.s file)
- static
- -
-
-
- -c
- Stop after compiling to object code (.o file)
- static
- -
-
-
-
-
hunk ./ghc/docs/users_guide/using.sgml 260
- The basic task of the ghc driver is to
+ The basic task of the ghc driver is to
hunk ./ghc/docs/users_guide/using.sgml 335
-Thus, a common invocation would be: ghc -c Foo.hs
+Thus, a common invocation would be: ghc -c Foo.hs
hunk ./ghc/docs/users_guide/using.sgml 354
+ The following options also affect which phases get run:
+
+
+
+
+
+
+ Run the C pre-processor on the Haskell source before
+ compiling it. See for more
+ details.
+
+
+
+
+
+
+
+ Use GHC's native code generator rather than compiling
+ via C. This will compile faster (up to twice as fast), but
+ may produce code that is slightly slower than compiling via
+ C. is the default when optimisation
+ is off (see ).
+
+
+
+
+
+
+
+
+ Compile via C instead of using the native code
+ generator. This is default for optimised compilations, and
+ on architectures for which GHC doesn't have a native code
+ generator.
+
+
+
hunk ./ghc/docs/users_guide/using.sgml 399
-
-
-
-
- Flag
- Description
- Static/Dynamic
- Reverse
-
-
-
-
- -hisuf
- set the suffix to use for interface files
- static
- -
-
-
- -o
- set output filename
- static
- -
-
-
- -odir
- set output directory
- static
- -
-
-
- -ohi
- set the filename in which to put the interface
- static
-
-
-
- -osuf
- set the output file suffix
- static
- -
-
-
-
-
hunk ./ghc/docs/users_guide/using.sgml 406
- .hc, .o, etc.,
+ .hc, .o, etc.,
hunk ./ghc/docs/users_guide/using.sgml 410
- last-run phase to file foo.
+ last-run phase to file foo.
hunk ./ghc/docs/users_guide/using.sgml 413
- counterintuitive: ghc -C -o foo.o foo.hs
+ counterintuitive: ghc -C -o foo.o foo.hs
hunk ./ghc/docs/users_guide/using.sgml 415
- foo.o, name notwithstanding!
+ foo.o, name notwithstanding!
hunk ./ghc/docs/users_guide/using.sgml 424
- you have several input files…
+ you have several input files…
hunk ./ghc/docs/users_guide/using.sgml 436
- The output files, Foo.o,
- Bar.o, and
- Bumble.o would be put into a
+ The output files, Foo.o,
+ Bar.o, and
+ Bumble.o would be put into a
hunk ./ghc/docs/users_guide/using.sgml 440
- machine (sun4,
- mips, etc). The directory must already
+ machine (sun4,
+ mips, etc). The directory must already
hunk ./ghc/docs/users_guide/using.sgml 445
- not affect where the interface files
+ not affect where the interface files
hunk ./ghc/docs/users_guide/using.sgml 447
- parse/Foo.hi,
- parse/Bar.hi, and
- gurgle/Bumble.hi.
+ parse/Foo.hi,
+ parse/Bar.hi, and
+ gurgle/Bumble.hi.
hunk ./ghc/docs/users_guide/using.sgml 470
- .o file suffix for object files to
+ .o file suffix for object files to
hunk ./ghc/docs/users_guide/using.sgml 477
- .hi file suffix for non-system
+ .hi file suffix for non-system
hunk ./ghc/docs/users_guide/using.sgml 483
- standard .hi/.o
+ standard .hi/.o
hunk ./ghc/docs/users_guide/using.sgml 485
- g_o to your make rule for
+ g_o to your make rule for
hunk ./ghc/docs/users_guide/using.sgml 500
-
-
-
-
- Flag
- Description
- Static/Dynamic
- Reverse
-
-
-
-
- -keep-hc-file
- retain intermediate .hc files
- static
- -
-
-
- -keep-s-file
- retain intermediate .s files
- static
- -
-
-
- -keep-raw-s-file
- retain intermediate .raw_s files
- static
- -
-
-
- -keep-tmp-files
- retain all intermediate temporary files
- static
- -
-
-
-
-
hunk ./ghc/docs/users_guide/using.sgml 574
-
-
-
-
- Flag
- Description
- Static/Dynamic
- Reverse
-
-
-
-
- -tmpdir
- set the directory for temporary files
- static
- -
-
-
-
-
-
hunk ./ghc/docs/users_guide/using.sgml 580
- in /tmp (or wherever your
+ in /tmp (or wherever your
hunk ./ghc/docs/users_guide/using.sgml 614
-
-
-
-
- Flag
- Description
- Static/Dynamic
- Reverse
-
-
-
-
- -W
- enable normal warnings
- static
- -w
-
-
- -w
- disable all warnings
- static
- -
-
-
- -Wall
- enable all warnings
- static
- -w
-
-
-
- -fwarn-deprecations
- warn about uses of functions & types that are deprecated
- dynamic
- -fno-warn-deprecations
-
-
-
- -fwarn-duplicate-exports
- warn when an entity is exported multiple times
- dynamic
- -fno-warn-duplicate-exports
-
-
-
- -fwarn-hi-shadowing
- warn when a .hi file in the
- current directory shadows a library
- dynamic
- -fno-warn-hi-shadowing
-
-
-
- -fwarn-incomplete-patterns
- warn when a pattern match could fail
- dynamic
- -fno-warn-incomplete-patterns
-
-
-
- -fwarn-missing-fields
- warn when fields of a record are uninitialised
- dynamic
- -fno-warn-missing-fields
-
-
-
- -fwarn-missing-methods
- warn when class methods are undefined
- dynamic
- -fno-warn-missing-methods
-
-
-
- -fwarn-missing-signatures
- warn about top-level functions without signatures
- dynamic
- -fno-warn-missing-signatures
-
-
-
- -fwarn-name-shadowing
- warn when names are shadowed
- dynamic
- -fno-warn-name-shadowing
-
-
-
- -fwarn-overlapping-patterns
- warn about overlapping patterns
- dynamic
- -fno-warn-overlapping-patterns
-
-
-
- -fwarn-simple-patterns
- warn about lambda-patterns that can fail
- dynamic
- -fno-warn-simple-patterns
-
-
-
- -fwarn-type-defaults
- warn when defaulting happens
- dynamic
- -fno-warn-type-defaults
-
-
-
- -fwarn-unused-binds
- warn about bindings that are unused
- dynamic
- -fno-warn-unused-binds
-
-
-
- -fwarn-unused-imports
- warn about unnecessary imports
- dynamic
- -fno-warn-unused-imports
-
-
-
- -fwarn-unused-matches
- warn about variables in patterns that aren't used
- dynamic
- -fno-warn-unused-matches
-
-
-
-
-
hunk ./ghc/docs/users_guide/using.sgml 900
-
-Separate compilation
-
-
-
-separate compilation
-recompilation checker
-make and recompilation
-This section describes how GHC supports separate compilation.
-
-
-
-Interface files
-
-
-
-interface files
-.hi files
-
-
-
-When GHC compiles a source file F which contains a module A, say,
-it generates an object F.o, and a companion interface
-fileA.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.
-
-
-
-NOTE: Having the name of the interface file follow the module name and
-not the file name, means that working with tools such as make
-become harder. make implicitly assumes that any output files
-produced by processing a translation unit will have file names that
-can be derived from the file name of the translation unit. For
-instance, pattern rules becomes unusable. For this reason, we
-recommend you stick to using the same file name as the module name.
-
-
-
-The interface file for A contains information needed by the compiler
-when it compiles any module B that imports A, whether directly or
-indirectly. When compiling B, GHC will read A.hi to find the
-details that it needs to know about things defined in A.
-
-
-
-Furthermore, when compiling module C which imports B, GHC may
-decide that it needs to know something about A—for example, B
-might export a function that involves a type defined in A. In this
-case, GHC will go and read A.hi even though C does not explicitly
-import A at all.
-
-
-
-The interface file may contain all sorts of things that aren't
-explicitly exported from A by the programmer. For example, even
-though a data type is exported abstractly, A.hi will contain the
-full data type definition. For small function definitions, A.hi
-will contain the complete definition of the function. For bigger
-functions, A.hi will contain strictness information about the
-function. And so on. GHC puts much more information into .hi files
-when optimisation is turned on with the flag. Without it
-puts in just the minimum; with it lobs in a whole pile of stuff.
-optimsation, effect on .hi files
-
-
-
-A.hi should really be thought of as a compiler-readable version of
-A.o. If you use a .hi file that wasn't generated by the same
-compilation run that generates the .o file the compiler may assume
-all sorts of incorrect things about A, resulting in core dumps and
-other unpleasant happenings.
-
-
-
-
-
-Finding interface files
-
-
-
-interface files, finding them
-finding interface files
-
-
-
-In your program, you import a module Foo by saying
-import Foo. GHC goes looking for an interface file, Foo.hi.
-It has a builtin list of directories (notably including .) where
-it looks.
-
-
-
-
-
-
-
-
-
--i<dirs> optionThis flag
-prepends a colon-separated list of dirs to the “import
-directories” list.
-See also for the significance of using
-relative and absolute pathnames in the list.
-
-
-
-
-
-
-
-
-resets the “import directories” list back to nothing.
-
-
-
-
-
-
-
-
--fno-implicit-prelude option
-GHC normally imports Prelude.hi files for you. If you'd rather it
-didn't, then give it a option.
-The idea is that you can then import a Prelude of your own. (But don't call it Prelude;
-the Haskell module namespace is flat, and you must not conflict with any Prelude module.)
-
-
-Even though you have not imported the Prelude, all the built-in syntax still refers to
-the built-in Haskell Prelude types and values, as specified by the Haskell Report.
-For example, the type [Int]
-still means Prelude.[] Int; tuples continue to refer to the standard Prelude
-tuples; the translation for list comprehensions continues to use Prelude.map etc.
-
- With one group of exceptions! You may want to define your own numeric class hierarchy.
-It completely defeats that purpose if the literal "1" means "Prelude.fromInteger 1",
-which is what the Haskell Report specifies. So the flag causes
-the following pieces of built-in syntax to refer to whatever is in scope, not the Prelude versions:
-
-
-
-Integer and fractional literals mean "fromInteger 1" and "fromRational 3.2",
-not the Prelude-qualified versions; both in expressions and in patterns.
-
-
-
-
-Negation (e.g. "- (f x)") means "negate (f x)" (not Prelude.negate).
-
-
-
-
-In an n+k pattern, the standard Prelude Ord class is used for comparison, but the
-necessary subtraction uses
-whatever "(-)" is in scope (not "Prelude.(-)").
-
-
-
-
-
-
-
-
-
-
-
--I<dir> option
-Once a Haskell module has been compiled to C (.hc file), you may
-wish to specify where GHC tells the C compiler to look for .h files.
-(Or, if you are using the option-cpp option, where
-it tells the C pre-processor to look…) For this purpose, use a
-option in the usual C-ish way.
-
-
-
-
-
-
-
-
-
-
-Other options related to interface files
-
-
-
-interface files, options
-The interface output may be directed to another file
-bar2/Wurble.iface with the option -ohi
-<file> option (not recommended).
-
-
-
-To avoid generating an interface file at all, use a
-option.-nohi option
-
-
-
-The compiler does not overwrite an existing .hi interface file if
-the new one is byte-for-byte the same as the old one; this is friendly
-to make. When an interface does change, it is often enlightening to
-be informed. The -hi-diffs option option will
-make GHC run diff on the old and new .hi files. You can also
-record the difference in the interface file itself, the
--keep-hi-diffs option takes care of that.
-
-
-
-The .hi files from GHC contain “usage” information which changes
-often and uninterestingly. If you really want to see these changes
-reported, you need to use the
--hi-diffs-with-usages option
-option.
-
-
-
-Interface files are normally jammed full of compiler-produced
-pragmas, which record arities, strictness info, etc. If you
-think these pragmas are messing you up (or you are doing some kind of
-weird experiment), you can tell GHC to ignore them with the
--fignore-interface-pragmas
-option option.
-
-
-
-When compiling without optimisations on, the compiler is extra-careful
-about not slurping in data constructors and instance declarations that
-it will not need. If you believe it is getting it wrong and not
-importing stuff which you think it should, this optimisation can be
-turned off with and .
--fno-prune-tydecls option-fno-prune-instdecls
-option
-
-
-
-See also , which describes how the linker finds standard
-Haskell libraries.
-
-
-
-
-
-The recompilation checker
-
+ &separate;
+ &packages;
hunk ./ghc/docs/users_guide/using.sgml 903
-recompilation checker
+
+ Optimisation (code improvement)
hunk ./ghc/docs/users_guide/using.sgml 906
-
-
-
-
- option
-
-
-(On by default) Turn on recompilation checking. This will stop
-compilation early, leaving an existing .o file in
-place, if it can be determined that the module does not need to be
-recompiled.
-
-
-
-
-
- option
-
-
-Turn off recompilation checking.
-
-
-
-
-
-
-
-In the olden days, GHC compared the newly-generated
-.hi file with the previous version; if they were
-identical, it left the old one alone and didn't change its
-modification date. In consequence, importers of a module with an
-unchanged output .hi file were not recompiled.
-
-
-
-This doesn't work any more. In our earlier example, module
-C does not import module A
-directly, yet changes to A.hi should force a
-recompilation of C. And some changes to
-A (changing the definition of a function that
-appears in an inlining of a function exported by B,
-say) may conceivably not change B.hi one jot. So
-now…
-
-
-
-GHC keeps a version number on each interface file, and on each type
-signature within the interface file. It also keeps in every interface
-file a list of the version numbers of everything it used when it last
-compiled the file. If the source file's modification date is earlier
-than the .o file's date (i.e. the source hasn't
-changed since the file was last compiled), and the
- is given on the command line, GHC will be
-clever. It compares the version numbers on the things it needs this
-time with the version numbers on the things it needed last time
-(gleaned from the interface file of the module being compiled); if
-they are all the same it stops compiling rather early in the process
-saying “Compilation IS NOT 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 copy.
-
-
-
-
-
-
-Using <Command>make</Command>
-
-
-
-make
-
-
-
-It is reasonably straightforward to set up a 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)
+ optimisation
+ improvement, code
hunk ./ghc/docs/users_guide/using.sgml 909
-SRCS = Main.lhs Foo.lhs Bar.lhs
-OBJS = Main.o Foo.o Bar.o
-
-.SUFFIXES : .o .hs .hi .lhs .hc .s
-
-cool_pgm : $(OBJS)
- rm $@
- $(HC) -o $@ $(HC_OPTS) $(OBJS)
-
-# Standard suffix rules
-.o.hi:
- @:
-
-.lhs.o:
- $(HC) -c $< $(HC_OPTS)
-
-.hs.o:
- $(HC) -c $< $(HC_OPTS)
-
-# 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.)
-
-
-
-Note the cheesy .o.hi rule: It records the dependency of the
-interface (.hi) file on the source. The rule says a .hi file can
-be made from a .o file by doing…nothing. Which is true.
-
-
-
-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 Foo.s have an
-earlier modification date than Baz.hi, then the out-of-date file
-must be brought up to date. To bring it up to date, make looks for
-a rule to do so; one of the preceding suffix rules does the job
-nicely.
-
-
-
-
-
- Dependency generation
- dependencies in Makefiles
- Makefile dependencies
-
- Putting inter-dependencies of the form Foo.o :
- Bar.hi into your Makefile by hand
- is rather error-prone. Don't worry, GHC has support for
- 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 make
- depend before you do make
- cool_pgm. ghc -M will append
- the needed dependencies to your
- Makefile.
-
- In general, if module A contains the
- line
-
-
-import B ...blah...
-
-
- then ghc -M will generate a dependency
- line of the form:
-
-
-A.o : B.hi
-
-
- If module A contains the line
-
-
-import {-# SOURCE #-} B ...blah...
-
-
- then ghc -M will generate a dependency
- line of the form:
-
-
-A.o : B.hi-boot
-
+ The options specify convenient
+ “packages” of optimisation flags; the
+ options described later on specify
+ individual optimisations to be turned on/off;
+ the options specify
+ machine-specific optimisations to be turned
+ on/off.
hunk ./ghc/docs/users_guide/using.sgml 917
- (See for details of interface files.)
- If A imports multiple modules, then there
- will be multiple lines with A.o as the
- target.
+
+ <option>-O*</option>: convenient “packages” of optimisation flags.
hunk ./ghc/docs/users_guide/using.sgml 920
- By default, ghc -M generates all the
- dependencies, and then concatenates them onto the end of
- makefile (or Makefile
- if makefile doesn't exist) bracketed by the
- lines "# DO NOT DELETE: Beginning of Haskell
- dependencies" and "# DO NOT DELETE: End
- of Haskell dependencies". If these lines already
- exist in the makefile, then the old
- dependencies are deleted first.
+ There are many options that affect
+ the quality of code produced by GHC. Most people only have a
+ general goal, something like “Compile quickly” or
+ “Make my program run like greased lightning.” The
+ following “packages” of optimisations (or lack
+ thereof) should suffice.
hunk ./ghc/docs/users_guide/using.sgml 927
- Internally, GHC uses a script to generate the
- dependencies, called mkdependHS. This script
- has some options of its own, which you might find useful.
- Options can be passed directly to mkdependHS
- with GHC's -optdep option. For example, to
- generate the dependencies into a file called
- .depend instead of
- Makefile:
-
-
-ghc -M -optdep-f optdep.depend ...
-
-
- The full list of options accepted by
- mkdependHS is:
+ 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 ).
hunk ./ghc/docs/users_guide/using.sgml 938
-
+ No -type option specified:
+ -O* not specified
hunk ./ghc/docs/users_guide/using.sgml 941
- Turn off warnings about interface file shadowing.
+ This is taken to mean: “Please compile
+ quickly; I'm not over-bothered about compiled-code
+ quality.” So, for example: ghc -c
+ Foo.hs
hunk ./ghc/docs/users_guide/using.sgml 949
-
+ :
+
hunk ./ghc/docs/users_guide/using.sgml 952
- Use blah as the makefile,
- rather than makefile or
- Makefile. If
- blah doesn't exist,
- mkdependHS creates it. We often use
- to put the dependencies in
- .depend and then
- include the file
- .depend into
- Makefile.
+ Means “turn off all optimisation”,
+ reverting to the same settings as if no
+ options had been specified. Saying
+ can be useful if
+ eg. make has inserted a
+ on the command line already.
hunk ./ghc/docs/users_guide/using.sgml 962
-
+ or :
+ -O option
+ -O1 option
+ optimisenormally
hunk ./ghc/docs/users_guide/using.sgml 967
- Use .<osuf> as the
- "target file" suffix ( default: o).
- Multiple flags are permitted (GHC2.05
- onwards). Thus "" will
- generate dependencies for .hc and
- .o files.
+ Means: “Generate good-quality code without
+ taking too long about it.” Thus, for example:
+ ghc -c -O Main.lhs
hunk ./ghc/docs/users_guide/using.sgml 974
-
+ :
+ -O2 option
+ optimiseaggressively
hunk ./ghc/docs/users_guide/using.sgml 978
- Make extra dependencies that declare that files with
- suffix
- .<suf>_<osuf>
- depend on interface files with suffix
- .<suf>_hi, or (for
- {-# SOURCE #-}
- imports) on .hi-boot. Multiple
- flags are permitted. For example,
- will make dependencies
- for .hc on .hi,
- .a_hc on
- .a_hi, and
- .b_hc on
- .b_hi. (Useful in conjunction
- with NoFib "ways".)
-
-
+ Means: “Apply every non-dangerous
+ optimisation, even if it means significantly longer
+ compile times.”
hunk ./ghc/docs/users_guide/using.sgml 982
-
-
-
- Regard <file> as
- "stable"; i.e., exclude it from having dependencies on
- it.
-
-
+ The avoided “dangerous” optimisations
+ are those that can make runtime or space
+ worse if you're unlucky. They are
+ normally turned on or off individually.
hunk ./ghc/docs/users_guide/using.sgml 987
-
-
-
- same as
+ At the moment, is
+ unlikely to produce better code than
+ .
hunk ./ghc/docs/users_guide/using.sgml 994
-
+ :
+ -O2-for-C option
+ gcc, invoking with -O2
hunk ./ghc/docs/users_guide/using.sgml 998
- Regard the colon-separated list of directories
- <dirs> as containing stable,
- don't generate any dependencies on modules therein.
+ Says to run GCC with , which may
+ be worth a few percent in execution speed. Don't forget
+ , lest you use the native-code
+ generator and bypass GCC altogether!
hunk ./ghc/docs/users_guide/using.sgml 1006
-
+ :
+ -Ofile <file> option
+ optimising, customised
hunk ./ghc/docs/users_guide/using.sgml 1010
- same as .
-
-
+ (NOTE: not supported yet in GHC 5.x. Please ask if
+ you're interested in this.)
+
+ For those who need absolute
+ control over exactly what options are
+ used (e.g., compiler writers, sometimes :-), a list of
+ options can be put in a file and then slurped in with
+ .
hunk ./ghc/docs/users_guide/using.sgml 1019
-
-
-
- Regard <file> as not
- "stable"; i.e., generate dependencies on it (if any). This
- option is normally used in conjunction with the
- option.
-
-
+ In that file, comments are of the
+ #-to-end-of-line variety; blank
+ lines and most whitespace is ignored.
hunk ./ghc/docs/users_guide/using.sgml 1023
-
-
-
- Regard prelude libraries as unstable, i.e., generate
- dependencies on the prelude modules used (including
- Prelude). This option is normally only
- used by the various system libraries. If a
- option is used, dependencies will
- also be generated on the library's interfaces.
+ Please ask if you are baffled and would like an
+ example of !
hunk ./ghc/docs/users_guide/using.sgml 1029
-
-
-
-How to compile mutually recursive modules
-
-
-
-module system, recursion
-recursion, between modules
-
-
-
-Currently, the compiler does not have proper support for dealing with
-mutually recursive modules:
-
-
-
-
-
-module A where
-
-import B
-
-newtype TA = MkTA Int
+ 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 lots of coffee breaks).
hunk ./ghc/docs/users_guide/using.sgml 1035
-f :: TB -> TA
-f (MkTB x) = MkTA x
---------
-module B where
-
-import A
-
-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, to get mutually
-recursive modules off the ground, you need to hand write an interface
-file for A or B, so as to break the loop. These hand-written
-interface files are called hi-boot files, and are placed in a file
-called <module>.hi-boot. To import from an hi-boot file instead
-of the standard .hi file, use the following syntax in the importing module:
-hi-boot 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 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.
-
-
-
-For the example at hand, the boot interface file for A would look like
-the following:
-
-
-
-
-
-__interface A 1 404 where
-__export A TA{MkTA} ;
-1 newtype TA = MkTA PrelBase.Int ;
-
-
-
-
-
-The syntax is essentially the same as a normal .hi file
-(unfortunately), but you can usually tailor an existing .hi file to
-make a .hi-boot file.
-
-
-
-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. The “404” is
-the version number of the interface file syntax; we change it when
-we change the syntax of interface files so that you get a better error message when
-you try to read an old-format file with a new-format compiler.
-
-
-
-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 404 where
-__export A TA;
-1 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.
-
-
-
-
-
-
-
- Packages
- packages
-
- Packages are collections of libraries, conveniently grouped
- together as a single entity. The package system is flexible: a
- package may consist of Haskell code, foreign language code (eg. C
- libraries), or a mixture of the two. A package is a good way to
- group together related Haskell modules, and is essential if you
- intend to make the modules into a Windows DLL (see below).
-
- Because packages can contain both Haskell and C libraries, they
- are also a good way to provide convenient access to a Haskell
- layer over a C library.
-
- GHC comes with several packages (see ), and packages can be added/removed from an
- existing GHC installation.
-
-
- Listing the available packages
- packages
- listing
-
- To see what packages are currently installed, use the
- --list-packages option:
- --list-packages
-
-
-
- $ ghc --list-packages
- gmp, rts, std, lang, concurrent, data, net, posix, text, util
-
-
- Note that your GHC installation might have a slightly
- different set of packages installed.
+ The easiest way to see what (etc.)
+ “really mean” is to run with ,
+ then stand back in amazement.
+
hunk ./ghc/docs/users_guide/using.sgml 1040
- The gmp and rts
- packages are always present, and represent the multi-precision
- integer and runtime system libraries respectively. The
- std package contains the Haskell prelude.
- The rest of the packages are optional libraries.
+
+ <option>-f*</option>: platform-independent flags
hunk ./ghc/docs/users_guide/using.sgml 1043
-
+ -f* options (GHC)
+ -fno-* options (GHC)
hunk ./ghc/docs/users_guide/using.sgml 1046
-
- Using a package
- packages
- using
-
- To use a package, add the -package flag
- to the command line:
+ These flags turn on and off individual optimisations.
+ They are normally set via the options
+ described above, and as such, you shouldn't need to set any of
+ them explicitly (indeed, doing so could lead to unexpected
+ results). However, there are one or two that may be of
+ interest:
hunk ./ghc/docs/users_guide/using.sgml 1055
-
- -package <lib> option
+ :
hunk ./ghc/docs/users_guide/using.sgml 1057
- This option brings into scope all the modules from
- package <lib> (they still have to
- be imported in your Haskell source, however). It also
- causes the relevant libraries to be linked when linking is
- being done.
+
+ When this option is given, intermediate floating
+ point values can have a greater
+ precision/range than the final type. Generally this is a
+ good thing, but some programs may rely on the exact
+ precision/range of
+ Float/Double values
+ and should not use this option for their compilation.
hunk ./ghc/docs/users_guide/using.sgml 1067
-
-
- Some packages depend on other packages, for example the
- text package makes use of some of the modules
- in the lang package. The package system
- takes care of all these dependencies, so that when you say
- -package text on the command line, you
- automatically get -package lang too.
-
-
-
- Building a package from Haskell source
- packages
- building
-
- It takes some special considerations to build a new
- package:
hunk ./ghc/docs/users_guide/using.sgml 1068
-
-
- A package may contain several Haskell modules. A
- package may span many directories, or many packages may
- exist in a single directory. Packages may not be mutually
- recursive.
-
-
-
- A package has a name
- (e.g. std)
-
-
-
- The Haskell code in a package may be built into one or
- more Unix libraries (e.g. libHSfoo.a),
- or a single DLL on Windows
- (e.g. HSfoo.dll). The restriction to a
- single DLL on Windows is that the package system is used to
- tell the compiler when it should make an inter-DLL call
- rather than an intra-DLL call (inter-DLL calls require an
- extra indirection).
-
-
-
- GHC does not maintain detailed cross-package
- dependency information. It does remember which modules in
- other packages the current module depends on, but not which
- things within those imported things.
-
-
-
- To compile a module which is to be part of a new package,
- use the -package-name option:
-
-
hunk ./ghc/docs/users_guide/using.sgml 1069
-
- -package-name
- option
+
+
+
hunk ./ghc/docs/users_guide/using.sgml 1073
- This option is added to the command line when
- compiling a module that is destined to be part of package
- foo. If this flag is omitted then the
- default package Main is assumed.
+ Turns off the strictness analyser; sometimes it eats
+ too many cycles.
hunk ./ghc/docs/users_guide/using.sgml 1077
-
-
- Failure to use the -package-name option
- when compiling a package will result in disaster on Windows, but
- is relatively harmless on Unix at the moment (it will just cause
- a few extra dependencies in some interface files). However,
- bear in mind that we might add support for Unix shared libraries
- at some point in the future.
-
- It is worth noting that on Windows, because each package
- is built as a DLL, and a reference to a DLL costs an extra
- indirection, intra-package references are cheaper than
- inter-package references. Of course, this applies to the
- Main package as well.
-
-
-
- Package management
- packages
- management
-
- GHC uses a package configuration file, called
- packages.conf, which can be found in your GHC
- install directory. This file isn't intended to be edited
- directly, instead GHC provides options for adding & removing
- packages:
hunk ./ghc/docs/users_guide/using.sgml 1078
-
hunk ./ghc/docs/users_guide/using.sgml 1079
-
- --add-package
- option
+
+
+
hunk ./ghc/docs/users_guide/using.sgml 1083
- Reads a package specification (see below) on stdin,
- and adds it to the database of installed packages. The
- package specification must be a package that isn't already
- installed.
+ Turns off the CPR (constructed product result)
+ analysis; it is somewhat experimental.
hunk ./ghc/docs/users_guide/using.sgml 1089
-
- --delete-package
- option
+ :
hunk ./ghc/docs/users_guide/using.sgml 1091
- Removes the specified package from the installed
- configuration.
-
-
-
+
+ strict constructor fields
+ constructor fields, strict
hunk ./ghc/docs/users_guide/using.sgml 1095
- In both cases, the old package configuration file is saved
- in packages.conf.old in your GHC install
- directory, so in an emergency you can always copy this file into
- package.conf to restore the old
- settings.
+ This option causes all constructor fields which are
+ marked strict (i.e. “!”) to be unboxed or
+ unpacked if possible. For example:
hunk ./ghc/docs/users_guide/using.sgml 1099
- A package specification looks like this:
+
+data T = T !Float !Float
+
hunk ./ghc/docs/users_guide/using.sgml 1103
-
- Package {
- name = "mypkg",
- import_dirs = ["/usr/local/lib/imports/mypkg"],
- library_dirs = ["/usr/local/lib"],
- hs_libraries = ["HSmypkg" ],
- extra_libraries = ["HSmypkg_cbits"],
- include_dirs = [],
- c_includes = ["HsMyPkg.h"],
- package_deps = ["text", "data"],
- extra_ghc_opts = [],
- extra_cc_opts = [],
- extra_ld_opts = ["-lmy_clib"]
- }
-
+ will create a constructor T
+ containing two unboxed floats if the
+ flag is given.
+ This may not always be an optimisation: if the
+ T constructor is scrutinised and the
+ floats passed to a non-strict function for example, they
+ will have to be reboxed (this is done automatically by the
+ compiler).
hunk ./ghc/docs/users_guide/using.sgml 1112
- Components of a package specification may be specified in
- any order, and are:
+ This option should only be used in conjunction with
+ , in order to expose unfoldings to the
+ compiler so the reboxing can be removed as often as
+ possible. For example:
hunk ./ghc/docs/users_guide/using.sgml 1117
-
-
- name
- name
- package specification
-
- The package's name, for use with
- the -package flag and as listed in the
- --list-packages list.
-
-
-
+
+f :: T -> Float
+f (T f1 f2) = f1 + f2
+
hunk ./ghc/docs/users_guide/using.sgml 1122
-
- import_dirs
- import_dirs
- package specification
-
- A list of directories containing interface files
- (.hi files) for this package.
-
-
+ The compiler will avoid reboxing
+ f1 and f2 by
+ inlining + on floats, but only when
+ is on.
hunk ./ghc/docs/users_guide/using.sgml 1127
-
- library_dirs
- library_dirs
- package specification
-
- A list of directories containing libraries for this
- package.
-
-
+ Any single-constructor data is eligible for
+ unpacking; for example
hunk ./ghc/docs/users_guide/using.sgml 1130
-
- hs_libraries
- hs_libraries
- package specification
-
- A list of libraries containing Haskell code for this
- package, with the .a or
- .dll suffix omitted. On Unix, the
- lib prefix is also omitted.
-
-
+
+data T = T !(Int,Int)
+
hunk ./ghc/docs/users_guide/using.sgml 1134
-
- extra_libraries
- extra_libraries
- package specification
-
- A list of extra libraries for this package. The
- difference between hs_libraries and
- extra_libraries is that
- hs_libraries normally have several
- versions, to support profiling, parallel and other build
- options. The various versions are given different
- suffixes to distinguish them, for example the profiling
- version of the standard prelude library is named
- libHSstd_p.a, with the
- _p indicating that this is a profiling
- version. The suffix is added automatically by GHC for
- hs_libraries only, no suffix is added
- for libraries in
- extra_libraries.
+ will store the two Ints directly
+ in the T constructor, by flattening
+ the pair. Multi-level unpacking is also supported:
hunk ./ghc/docs/users_guide/using.sgml 1138
- Also, extra_libraries are placed
- on the linker command line before the
- hs_libraries for the same package. If
- your package has dependencies in the other direction, you
- might need to make two separate packages.
-
-
+
+data T = T !S
+data S = S !Int !Int
+
hunk ./ghc/docs/users_guide/using.sgml 1143
-
- include_dirs
- include_dirs
- package specification
-
- A list of directories containing C includes for this
- package (maybe the empty list).
+ will store two unboxed Int#s
+ directly in the T constructor.
hunk ./ghc/docs/users_guide/using.sgml 1149
- c_includes
- c_includes
- package specification
+
+
hunk ./ghc/docs/users_guide/using.sgml 1152
- A list of files to include for via-C compilations
- using this package. Typically this include file will
- contain function prototypes for any C functions used in
- the package, in case they end up being called as a result
- of Haskell functions from the package being
- inlined.
+ Switches on an experimental "optimisation".
+ Switching it on makes the compiler a little keener to
+ inline a function that returns a constructor, if the
+ context is that of a thunk.
+
+ x = plusInt a b
+
+ If we inlined plusInt we might get an opportunity to use
+ update-in-place for the thunk 'x'.
hunk ./ghc/docs/users_guide/using.sgml 1165
- package_deps
- package_deps
- package specification
+ :
hunk ./ghc/docs/users_guide/using.sgml 1167
- A list of packages which this package depends
- on.
-
-
+
+ inlining, controlling
+ unfolding, controlling
hunk ./ghc/docs/users_guide/using.sgml 1171
-
- extra_ghc_opts
- extra_ghc_opts
- package specification
-
- Extra arguments to be added to the GHC command line
- when this package is being used.
+ (Default: 30) By raising or lowering this number,
+ you can raise or lower the amount of pragmatic junk that
+ gets spewed into interface files. (An unfolding has a
+ “size” that reflects the cost in terms of
+ “code bloat” of expanding that unfolding in
+ another module. A bigger function would be assigned a
+ bigger cost.)
hunk ./ghc/docs/users_guide/using.sgml 1182
- extra_cc_opts
- extra_cc_opts
- package specification
+ :
hunk ./ghc/docs/users_guide/using.sgml 1184
- Extra arguments to be added to the gcc command line
- when this package is being used (only for via-C
- compilations).
+
+ inlining, controlling
+ unfolding, controlling
+
+ (Default: 30) This option is similar to
+ , except
+ that it governs unfoldings within a single module.
+ Increasing this figure is more likely to result in longer
+ compile times than faster code. The next option is more
+ useful:
hunk ./ghc/docs/users_guide/using.sgml 1198
- extra_ld_opts
- extra_ld_opts
- package specification
+ :
hunk ./ghc/docs/users_guide/using.sgml 1200
- Extra arguments to be added to the gcc command line
- (for linking) when this package is being used.
+
+ inlining, controlling
+ unfolding, controlling
+
+ (Default: 8) This is the magic cut-off figure for
+ unfolding: below this size, a function definition will be
+ unfolded at the call-site, any bigger and it won't. The
+ size computed for a function depends on two things: the
+ actual size of the expression minus any discounts that
+ apply (see ).
hunk ./ghc/docs/users_guide/using.sgml 1214
- For examples of more package specifications, take a look
- at the package.conf in your GHC
- installation.
hunk ./ghc/docs/users_guide/using.sgml 1215
-
-
-
-
-Optimisation (code improvement)
-
-
-
-optimisation (GHC)
-improvement, code (GHC)
-
hunk ./ghc/docs/users_guide/using.sgml 1216
-
-The options specify convenient “packages” of optimisation
-flags; the options described later on specify
-individual optimisations to be turned on/off; the
-options specify machine-specific optimisations to be turned
-on/off.
-
-
-
-<option>-O*</option>: convenient “packages” of optimisation flags.
-
-
-
--O options
-
-
-
-There are many options that affect the quality of code
-produced by GHC. Most people only have a general goal, something like
-“Compile quickly” or “Make my program run like greased lightning.”
-The 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 ).
-
-
-
-
-
-
-No -type option specified:
--O* not specified
-
-
-This is taken to mean: “Please compile quickly; I'm not over-bothered
-about compiled-code quality.” So, for example: ghc -c Foo.hs
-
-
-
-
- or :
--O option
--O1 option
-optimisenormally
-
-
-Means: “Generate good-quality code without taking too long about
-it.” Thus, for example: ghc -c -O Main.lhs
-
-
-
-
-:
--O2 option
-optimiseaggressively
-
-
-Means: “Apply every non-dangerous optimisation, even if it means
-significantly longer compile times.”
-
-
-
-The avoided “dangerous” optimisations are those that can make
-runtime or space worse if you're unlucky. They are
-normally turned on or off individually.
-
-
-
-At the moment, is unlikely to produce
-better code than .
-
-
-
-
-:
--O2-for-C option
-gcc, invoking with -O2
-
-
-Says to run GCC with , which may be worth a few percent in
-execution speed. Don't forget , lest you use the native-code
-generator and bypass GCC altogether!
-
-
-
-
-:
--Onot option
-optimising, reset
-
-
-This option will make GHC “forget” any
-ish options it has seen so far. Sometimes useful;
-for example: make all
-EXTRA_HC_OPTS=-Onot.
-
-
-
-
-:
--Ofile <file> option
-optimising, customised
-
-
-For those who need absolute control over
-exactly what options are used (e.g., compiler
-writers, sometimes :-), a list of options can be put in a file and
-then slurped in with .
-
-
-
-In that file, comments are of the
-#-to-end-of-line variety; blank lines and most
-whitespace is ignored.
-
-
-
-Please ask if you are baffled and would like an example of !
-
-
-
-
-
-
-
-At Glasgow, 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 lots of coffee breaks).
-
-
-
-The easiest way to see what (etc.) “really mean” is to run with
-, then stand back in amazement. Alternatively, just look at the
-HsC_minus<blah> lists in the GHC driver script.
-
-
-
-
-
-<option>-f*</option>: platform-independent flags
-
-
--f* options (GHC)
--fno-* options (GHC)
-
-
-
-Flags can be turned off individually. (NB: I hope you have a
-good reason for doing this…) To turn off the flag, just use
-the flag.-fno-<opt> anti-option So, for
-example, you can say , which will then drop out
-any running of the strictness analyser.
-
-
-
-The options you are most likely to want to turn off are:
-
-
-
-
-
--fno-strictness option (strictness
-analyser, because it is sometimes slow),
-
-
-
-
-
--fno-specialise option (automatic
-specialisation of overloaded functions, because it can make your code
-bigger) (US spelling also accepted), and
-
-
-
-
-
--fno-cpr-analyse option switches off the CPR (constructed product
-result) analyser.
-
-
-
-
-
-
-
-
-Should you wish to turn individual flags on, you are advised
-to use the option, described above. Because the order in
-which optimisation passes are run is sometimes crucial, it's quite
-hard to do with command-line options.
-
-
-
-Here are some “dangerous” optimisations you might want to try:
-
-
-
-:
-
-
--fvia-C option
-native code generator, turning off
-
-
-
-Compile via C, and don't use the native-code generator. (There are many
-cases when GHC does this on its own.) You might pick up a little bit of
-speed by compiling via C (e.g. for floating-point intensive code on Intel).
-If you use _casm_s (which are utterly
-deprecated), you probably have to use
-.
-
-
-
-The lower-case incantation, , is synonymous.
-
-
-
-Compiling via C will probably be slower (in compilation time) than
-using GHC's native code generator.
-
-
-
-
-:
-
-
--funfolding-interface-threshold option
-inlining, controlling
-unfolding, controlling
-(Default: 30) By raising or lowering this number, you can raise or
-lower the amount of pragmatic junk that gets spewed into interface
-files. (An unfolding has a “size” that reflects the cost in terms
-of “code bloat” of expanding that unfolding in another module. A
-bigger function would be assigned a bigger cost.)
-
-
-
-
-:
-
-
--funfolding-creation-threshold option
-inlining, controlling
-unfolding, controlling
-(Default: 30) This option is similar to
-, except that it governs unfoldings
-within a single module. Increasing this figure is more likely to
-result in longer compile times than faster code. The next option is
-more useful:
-
-
-
-
-:
-
-
--funfolding-use-threshold option
-inlining, controlling
-unfolding, controlling
-(Default: 8) This is the magic cut-off figure for unfolding: below
-this size, a function definition will be unfolded at the call-site,
-any bigger and it won't. The size computed for a function depends on
-two things: the actual size of the expression minus any discounts that
-apply (see ).
-
-
-
-
-
-:
-
-
-Switches on an experimental "optimisation". Switching it on makes the compiler
-a little keener to inline a function that returns a constructor, if the context is
-that of a thunk.
-
- x = plusInt a b
-
-If we inlined plusInt we might get an opportunity to use update-in-place for
-the thunk 'x'.
-
-
-
-
-
-:
-
-
--funbox-strict-fields option
-strict constructor fields
-constructor fields, strict
-
-
-
-This option causes all constructor fields which are marked strict
-(i.e. “!”) to be unboxed or unpacked if possible. For example:
-
-
-
-
-
-data T = T !Float !Float
-
-
-
-
-
-will create a constructor T containing two unboxed floats if the
- flag is given. This may not always be an
-optimisation: if the T constructor is scrutinised and the floats
-passed to a non-strict function for example, they will have to be
-reboxed (this is done automatically by the compiler).
-
-
-
-This option should only be used in conjunction with , in order to
-expose unfoldings to the compiler so the reboxing can be removed as
-often as possible. For example:
-
-
-
-
-
-f :: T -> Float
-f (T f1 f2) = f1 + f2
-
-
-
-
-
-The compiler will avoid reboxing f1 and f2 by inlining + on
-floats, but only when is on.
-
-
-
-Any single-constructor data is eligible for unpacking; for example
-
-
-
-
-
-data T = T !(Int,Int)
-
-
-
-
-
-will store the two Ints directly in the T constructor, by flattening
-the pair. Multi-level unpacking is also supported:
-
-
-
-
-
-data T = T !S
-data S = S !Int !Int
-
-
-
-
-
-will store two unboxed Int#s directly in the T constructor.
-
-
-
-
-:
-
-
-This option (which does not work with the native-code generator)
-tells the compiler to add extra code to test for already-evaluated
-values. You win if you have lots of such values during a run of your
-program, you lose otherwise. (And you pay in extra code space.)
-
-
-
-We have not played with enough to recommend it.
-(For all we know, it doesn't even work anymore… Sigh.)
-
-
-
-
-:
-
-
-When this option is given, intermediate floating point values can have
-a greater precision/range than the final type.
-Generally this is a good thing, but some programs may rely on the
-exact precision/range of Float/Double
-values and should not use this option for their compilation.
-
-
-
-
-
-
-
-
-
-<option>-m*</option>: platform-specific flags
-
-
--m* options (GHC)
-platform-specific options
-machine-specific options
-
-
-
-Some flags only make sense for particular target platforms.
-
-
-
-
-
-
-:
-
-
-(SPARC machines)-mv8 option (SPARC only)
-Means to pass the like-named option to GCC; it says to use the
-Version 8 SPARC instructions, notably integer multiply and divide.
-The similiar GCC options for SPARC also work, actually.
-
-
-
-
-:
-
-
-(HPPA machines)-mlong-calls option (HPPA only)
-Means to pass the like-named option to GCC. Required for Very Big
-modules, maybe. (Probably means you're in trouble…)
-
-
-
-
-:
-
-
-(iX86 machines)-monly-N-regs option (iX86 only)
-GHC tries to “steal” four registers from GCC, for performance
-reasons; it almost always works. However, when GCC is compiling some
-modules with four stolen registers, it will crash, probably saying:
-
-
-Foo.hc:533: fixed or forbidden register was spilled.
-This may be due to a compiler bug or to impossible asm
-statements or clauses.
-
-
-Just give some registers back with . Try `3' first,
-then `2'. If `2' doesn't work, please report the bug to us.
-
-
-
-
-
-
-
-
-
-Code improvement by the C compiler.
-
-
-
-optimisation by GCC
-GCC optimisation
-
-
-
-The C compiler (GCC) is run with turned on. (It has
-to be, actually).
-
-
-
-If you want to run GCC with —which may be worth a few
-percent in execution speed—you can give a
--O2-for-C option option.
-
-
-
-
-
-
-
-Options related to a particular phase
-
-
-
-The C pre-processor
-
-
-
-pre-processing: cpp
-C pre-processor options
-cpp, pre-processing with
-
-
-
-The C pre-processor cpp is run over your Haskell code only if the
- option -cpp option is given. Unless you are
-building a large system with significant doses of conditional
-compilation, you really shouldn't need it.
-
-
-
-:
-
-
--D<name> option
-Define macro <foo> in the usual way. NB: does not affect
- macros passed to the C compiler when compiling via C! For those,
-use the hack… (see ).
-
-
-
-
-:
-
-
--U<name> option
-Undefine macro <foo> in the usual way.
-
-
-
-
-:
-
-
--I<dir> option
-Specify a directory in which to look for #include files, in
-the usual C way.
-
-
-
-
-
-
-
-The GHC driver pre-defines several macros when processing Haskell
-source code (.hs or .lhs files):
-
-
-
-
-
-
-__HASKELL98__:
-
-
-__HASKELL98__
-If defined, this means that GHC supports the language defined by the
-Haskell 98 report.
-
-
-
-
-__HASKELL__=98:
-
-
-__HASKELL__
-In GHC 4.04 and later, the __HASKELL__ macro is defined as having
-the value 98.
-
-
-
-
-__HASKELL1__:
-
-
-__HASKELL1__ macro
-If defined to n, that means GHC supports the Haskell language
-defined in the Haskell report version 1.n. Currently 5. This
-macro is deprecated, and will probably disappear in future versions.
-
-
-
-
-__GLASGOW_HASKELL__:
-
-
-__GLASGOW_HASKELL__ macro
-For version n of the GHC system, this will be #defined to
-100n. So, for version 4.00, it is 400.
-
-
-
-With any luck, __GLASGOW_HASKELL__ will be undefined in all other
-implementations that support C-style pre-processing.
-
-
-
-(For reference: the comparable symbols for other systems are:
-__HUGS__ for Hugs and __HBC__ for Chalmers.)
-
-
-
-NB. This macro is set when pre-processing both Haskell source and C
-source, including the C source generated from a Haskell module
-(i.e. .hs, .lhs, .c and .hc files).
-
-
-
-
-__CONCURRENT_HASKELL__:
-
-
-__CONCURRENT_HASKELL__ macro
-This symbol is defined when pre-processing Haskell (input) and
-pre-processing C (GHC output). Since GHC from verion 4.00 now
-supports concurrent haskell by default, this symbol is always defined.
-
-
-
-
-__PARALLEL_HASKELL__:
-
-
-__PARALLEL_HASKELL__ macro
-Only defined when is in use! This symbol is defined when
-pre-processing Haskell (input) and pre-processing C (GHC output).
-
-
-
-
-
-
-
-Options other than the above can be forced through to the C
-pre-processor with the flags (see
-).
-
-
-
-A small word of warning: is not friendly to “string
-gaps”.-cpp vs string gapsstring gaps vs
--cpp. In other words, strings such as the following:
-
-
-
-
-
-strmod = "\
-\ p \
-\ "
-
-
-
-
-
-don't work with ; /usr/bin/cpp elides the
-backslash-newline pairs.
-
-
-
-However, it appears that if you add a space at the end of the line,
-then cpp (at least GNU cpp and possibly other cpps)
-leaves the backslash-space pairs alone and the string gap works as
-expected.
-
-
-
-
-
-Options affecting the C compiler (if applicable)
-
-
-
-include-file options
-C compiler options
-GCC options
-
-
-
-At the moment, quite a few common C-compiler options are passed on
-quietly to the C compilation of Haskell-compiler-generated C files.
-THIS MAY CHANGE. Meanwhile, options so sent are:
-
-
-
-
-
-
-
-
-
-
-
- do ANSI C (not K&R)
-
-
-
-
- be so
-
-
-
-
- (hack) short for “make GCC very paranoid”
-
-
-
-
-
-
-
--ansi option (for GCC)
--pedantic option (for GCC)
--dgcc-lint option (GCC paranoia)
-
-
-
-If you are compiling with lots of foreign calls, you may need to
-tell the C compiler about some #include files. There is no real
-pretty way to do this, but you can use this hack from the
-command-line:
-
-
-
-
-
-% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
-
-
-
-
-
-
-
-Linking and consistency-checking
-
-
-
-linker options
-ld options
-
-
-
-GHC has to link your code with various libraries, possibly including:
-user-supplied, GHC-supplied, and system-supplied ( math
-library, for example).
-
-
-
-
-
-
-:
-
-
--l<lib> option
-Link in a library named lib<FOO>.a which resides somewhere on the
-library directories path.
-
-
-
-Because of the sad state of most UNIX linkers, the order of such
-options does matter. Thus: ghc -lbar *.o is almost certainly
-wrong, because it will search libbar.abefore it has
-collected unresolved symbols from the *.o files.
-ghc *.o -lbar is probably better.
-
-
-
-The linker will of course be informed about some GHC-supplied
-libraries automatically; these are:
-
-
-
-
-
-
-
-
-
-
--l equivalent
-description
-
-
-
-
-
- basic runtime libraries
-
-
-
-
- standard Prelude library
-
-
-
-
- C support code for standard Prelude library
-
-
-
-
- GNU multi-precision library (for Integers)
-
-
-
-
-
-
-
-
-
-
--lHS library
--lHS_cbits library
--lHSrts library
--lgmp library
-
-
-
-
-:
-
-
--package <name> option
-
-
-
-If you are using a Haskell “package” (e.g., the POSIX
-library), just use the option, and the
-correct code should be linked in. See for
-more details.
-
-
-
-
-:
-
-
--L<dir> option
-Where to find user-supplied libraries… Prepend the directory
-<dir> to the library directories path.
-
-
-
-
-:
-
-
--static option
-Tell the linker to avoid shared libraries.
-
-
-
-
- and :
-
-
--no-link-chk option
--link-chk option
-consistency checking of executables
-By default, immediately after linking an executable, GHC verifies that
-the pieces that went into it were compiled with compatible flags; a
-“consistency check”.
-(This is to avoid mysterious failures caused by non-meshing of
-incompatibly-compiled programs; e.g., if one .o file was compiled
-for a parallel machine and the others weren't.) You may turn off this
-check with . You can turn it (back) on with
- (the default).
-
-
-
-
-:
-
-
--no-hs-main option
-linking Haskell libraries with foreign code
-
-
-
-In the event you want to include ghc-compiled code as part of another
-(non-Haskell) program, the RTS will not be supplying its definition of
-main() at link-time, you will have to. To signal that to the
-driver script when linking, use .
-
-
-
-Notice that since the command-line passed to the linker is rather
-involved, you probably want to use the ghc driver script to do the
-final link of your `mixed-language' application. This is not a
-requirement though, just try linking once with on to see what
-options the driver passes through to the linker.
-
-
-
-
-
-
-
+
hunk ./ghc/docs/users_guide/using.sgml 1218
-
+&phases;
hunk ./ghc/docs/users_guide/using.sgml 1221
-Using Concurrent Haskell
+Using Concurrent Haskell
hunk ./ghc/docs/users_guide/using.sgml 1250
-Using Parallel Haskell
+Using Parallel Haskell
hunk ./ghc/docs/users_guide/using.sgml 1264
-option both when compiling and
-linking. You will probably want to import
+option both when compiling and
+linking. You will probably want to import
hunk ./ghc/docs/users_guide/using.sgml 1285
-Dummy's guide to using PVM
+Dummy's guide to using PVM
hunk ./ghc/docs/users_guide/using.sgml 1292
-probably in your .cshrc or equivalent:
+probably in your .cshrc or equivalent:
hunk ./ghc/docs/users_guide/using.sgml 1308
-You use the pvmpvm command command to start PVM on your
+You use the pvmpvm command command to start PVM on your
hunk ./ghc/docs/users_guide/using.sgml 1321
-exit pvm, leaving it running
+exit pvm, leaving it running
hunk ./ghc/docs/users_guide/using.sgml 1325
-halt
+halt
hunk ./ghc/docs/users_guide/using.sgml 1330
-add <host>
-add <host> as a processor
+add <host>
+add <host> as a processor
hunk ./ghc/docs/users_guide/using.sgml 1335
-delete <host>
-delete <host>
+delete <host>
+delete <host>
hunk ./ghc/docs/users_guide/using.sgml 1340
-reset
+reset
hunk ./ghc/docs/users_guide/using.sgml 1345
-conf
+conf
hunk ./ghc/docs/users_guide/using.sgml 1350
-ps
+ps
hunk ./ghc/docs/users_guide/using.sgml 1355
-pstat <pid>
+pstat <pid>
hunk ./ghc/docs/users_guide/using.sgml 1365
-The PVM documentation can tell you much, much more about pvm!
+The PVM documentation can tell you much, much more about pvm!
hunk ./ghc/docs/users_guide/using.sgml 1371
-Parallelism profiles
+Parallelism profiles
hunk ./ghc/docs/users_guide/using.sgml 1385
-Parallelism profiles (à la hbcpp) can be generated with the
+Parallelism profiles (à la hbcpp) can be generated with the
hunk ./ghc/docs/users_guide/using.sgml 1388
-<full-path><program>.gr. These are then munged into a PostScript picture,
+<full-path><program>.gr. These are then munged into a PostScript picture,
hunk ./ghc/docs/users_guide/using.sgml 1390
-a.out on 8 processors, then view the parallelism profile, do:
+a.out on 8 processors, then view the parallelism profile, do:
hunk ./ghc/docs/users_guide/using.sgml 1406
-in ghc/utils/parallel/.
+in ghc/utils/parallel/.
hunk ./ghc/docs/users_guide/using.sgml 1412
-Other useful info about running parallel programs
+Other useful info about running parallel programs
hunk ./ghc/docs/users_guide/using.sgml 1420
-appears in /tmp/pvml.nnn, courtesy of PVM.
+appears in /tmp/pvml.nnn, courtesy of PVM.
hunk ./ghc/docs/users_guide/using.sgml 1425
-what's happening overall is: tail -f /tmp/pvml.nnn.
+what's happening overall is: tail -f /tmp/pvml.nnn.
hunk ./ghc/docs/users_guide/using.sgml 1431
-RTS options for Concurrent/Parallel Haskell
-
+RTS options for Concurrent/Parallel Haskell
+
hunk ./ghc/docs/users_guide/using.sgml 1483
-in the file <program>.qp. In the style of hbcpp, this profile
+in the file <program>.qp. In the style of hbcpp, this profile
hunk ./ghc/docs/users_guide/using.sgml 1489
-hbcpp profiling tools or if you are context switching at every heap
+hbcpp profiling tools or if you are context switching at every heap
hunk ./ghc/docs/users_guide/using.sgml 1501
-words in the heap for thread state and stack objects. (For
+words in the heap for thread state and stack objects. (For
hunk ./ghc/docs/users_guide/using.sgml 1513
-something…) per PVM processor. We use the standard debugger
+something…) per PVM processor. We use the standard debugger
hunk ./ghc/docs/users_guide/using.sgml 1515
-debugger2 script. We include ours in the GHC distribution,
-in ghc/utils/pvm/.
+debugger2 script. We include ours in the GHC distribution,
+in ghc/utils/pvm/.
hunk ./ghc/docs/users_guide/using.sgml 1550
+
+ Platform-specific Flags
+
+ -m* options
+ platform-specific options
+ machine-specific options
+
+ Some flags only make sense for particular target
+ platforms.
+
+
+
+
+ :
+
+ (SPARC machines)-mv8 option (SPARC
+ only) Means to pass the like-named
+ option to GCC; it says to use the Version 8 SPARC
+ instructions, notably integer multiply and divide. The
+ similiar GCC options for SPARC also
+ work, actually.
+
+
+
+
+ :
+
+ (HPPA machines)-mlong-calls option
+ (HPPA only) Means to pass the
+ like-named option to GCC. Required for Very Big modules,
+ maybe. (Probably means you're in trouble…)
+
+
+
+
+ :
+
+ (iX86 machines)-monly-N-regs
+ option (iX86 only) GHC tries to
+ “steal” four registers from GCC, for performance
+ reasons; it almost always works. However, when GCC is
+ compiling some modules with four stolen registers, it will
+ crash, probably saying:
+
+
+Foo.hc:533: fixed or forbidden register was spilled.
+This may be due to a compiler bug or to impossible asm
+statements or clauses.
+
+
+ Just give some registers back with
+ . Try `3' first, then `2'.
+ If `2' doesn't work, please report the bug to us.
+
+
+
+
+
+
hunk ./ghc/docs/users_guide/using.sgml 1611
+&flags
}