Home

The Glorious Glasgow Haskell Compilation System User`s Guide

1. The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 113 327 Flag Description Static Dynamic Reverse Enable Safe Haskell trusted fpackage trust package requirement for dynamic 7 trustworthy modules f set the limit for type ftype function yP denti function reductions Default dynamic PEATE is 200 Allow the user to write XAllowAmbiguousTy ambiguous types and the dynamic XNoAllowAmbiguous pes type inference engine to y Types infer them Enable arrow notation XArrows dynamic XNoArrows extension As of GHC 7 10 this option is not needed and should not be used Automatically XAutoDeriveTypea derive Typeable instances daria XNoAutoDeriveType ble for every datatype and type y able class declaration Implies XDeriveDataTypea ble XBangPatterns Enable bang patterns dynamic XNoBangPatterns Enable support for bina XBinaryLiterals terai PP iy dynamic XNoBinaryLiterals Enable the CAPI calling XCApiFFI dynamic XNoCAPIFFI convention XConstrainedClass Enable constrained class XNoConstrainedCla dynamic Methods methods ssMethods Enable a kind of XConstraintKinds A dynamic constraints XNoConstraintKinds XCPP Enable the C preprocessor dynamic XNoCPP XDataKinds Enable datatype promotion dynamic XNoDataKinds P XNoDefaultSi t Enable default signatures dynamic iii A XDefaultSignatures res j Enable deriving for an
2. The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 43 327 Chapter 3 Using runghc runghc allows you to run Haskell programs without first having to compile them 3 1 Flags The runghe commandline looks like runghc runghc flags GHC flags module program args The runghc flags are f path to ghc which tells runghc which GHC to use to run the program and help which prints usage information If it is not given then runghc will search for GHC in the directories in the system search path runghc will try to work out where the boundaries between runghc flags and GHC flags and program args and module are but you can use a flag if it doesn t get it right For example runghc fwarn unused bindings Foo means runghc won t try to use warn unused bindings as the path to GHC but instead will pass the flag to GHC If a GHC flag doesn t start with a dash then you need to prefix it with ghc arg or runghc will think that it is the program to run e g runghc package db ghc arg foo conf Main hs The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 44 327 Chapter 4 Using GHC 4 1 Getting started compiling programs In this chapter you ll find a complete reference to the GHC command line syntax including all 400 flags It s a large and complex system and there are lots of details so it can be quite hard to figure out how t
3. B instance OVERLAPPABLE context3 gt C a b where C instance OVERLAPPING context4 gt C Int Int where D Now suppose that the type inference engine needs to solve the constraint C Int Int This constraint matches instances A C and D but the last is more specific and hence is chosen If D did not exist then A and C would still be matched but neither is most specific In that case the program would be rejected unless XIncoherent Instances is enabled in which case it would be accepted and A or C would be chosen arbitrarily An instance declaration is more specific than another iff the head of former is a substitution instance of the latter For example D is more specific than C because you can get from C to D by substituting a Int GHC is conservative about committing to an overlapping instance For example 38 lol gt lla f x Suppose that from the RHS of f we get the constraint C b b But GHC does not commit to instance C because in a particular call of f b might be instantiate to Int in which case instance D would be more specific still So GHC rejects the program If however you add the flag XIncoherentInstances when compiling the module that contians D GHC will instead pick C without complaining about the problem of subsequent instantiations Notice that we gave a type signature to f so GHC had to check that f has the specified
4. PLAS DOC MO ab OO ALC lt EC OPTS Ths booto POORA SCE e lt TC OPTS Inter module dependencies Ho HOON a OS E IZA Foo imports Baz Manm Om Manine aca Masinivey Sass b OOm AB za 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 oe c0 S todas SEC e p lt iC 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 that the suffix rules are all repeated twice once for normal Haskell source files and once for hs boot files see Sec tion 4 7 9 Note also the inter module dependencies at the end of the Makefile which take the form 1009 ODMS LOS 3 Bemol 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 These dependencies can be generated automatically by ghc see Section 4 7 12 4 7 12 Dependency generation 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 g
5. iD eh Oe ee eA Aone The idea is there can be no legal calls to because every call will give rise to an ambiguous constraint Indeed the only purpose of the ambiguity check is to report functions that cannot possibly be called We could soundly omit the ambiguity check on type signatures entirely at the expense of delaying ambiguity errors to call sites Indeed the language extension XAllowAmbiguousTypes switches off the ambiguity check Ambiguity can be subtle Consider this example which uses functional dependencies class Dab a gt b where lok S93 JB Trae Joy gt ae The Int may well fix b at the call site so that signature should not be rejected Moreover the dependencies might be hidden Consider class X a b where class Dab a gt b where instance D ab gt X a b where lay 8 9 24 ala A gt a Here h s type looks ambiguous in b but here s a legal call Cette WES Trees That gives rise toa X Bool beta constraint and using the instance means we need D Bool beta and that fixes beta via D s fundep Behind all these special cases there is a simple guiding principle Consider f type LS oro Ela Oo RE G sx You would think that the definition of g would surely typecheck After all has exactly the same type and g f But in fact s type is instantiated and the instantiated constraints are solved against the constraints bound by g s signature So in the case an ambiguo
6. ignore package name Ignore package P dynamic set Add file to the package to be trusted package db file db stack dynamic clear package db Clear the package db stack dynamic no global Remove the global package package db db from the stack enero Add the global package db i global package db t the stack dynamic no user package Remove the user s package E db db from the stack dynai Add the user s package db user package db to th stick dynamic z no auto link Don t automatically link in dynamic packages the base and rts packages oe Expose package P and set it A eset distrust P Expose package P and set it to be distrusted dynamic set distrust all Distrust all packages by default dynamic set 4 19 12 Language options T Language options can be enabled either by a command line option Xblah or by a LANGUAGE blah pragma in the file itself See Section 7 1 Some options are enabled using fx flags Flag Description Static Dynamic Reverse set the limit for type class fcontext stack n context reduction Default dynamic is 100 Deprecated Enable most fglasgow exts eee ias Ne dynamic fno glasgow exts which ones firrefutable Make tuple pattern dynamic fno irrefutable tuples matching irrefutable tuples
7. osoo a 78 Optimisation code improvement ooo ee 78 4 10 1 Ox convenient packages of optimisation flags oaoa e ee 78 4 10 2 x platform independent flags o ooa a a 79 GHC Backends croacia e ee Boe i a 84 4 11 1 Native code Generator fasm a 84 4 11 2 LLVM Code Generator fllvm 2 0 es 84 4 11 3 C Code Generator fvia C ecs pa dos a p a a e E A a e a e E A e a o E 84 4 11 4 Unregisterised compilation 84 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 vii 4 12 4 13 4 14 4 15 4 16 4 17 4 18 Options related to a particular phase ee 85 4 12 1 Replacing the program for one Or more phases e 85 4 12 2 Forcing options to a particular phase e 85 4 12 3 Options affecting the C pre processor ee 86 4123 1 CPP and string faps i e axes edak oe aE SE A Behe a ewe esse ox 87 4 12 4 Options affecting a Haskell pre processor ee 87 4 12 5 Options affecting code generation 2 2 ee 88 4 12 6 Options affecting linking 2 2 2 0 0 00 0000000000000 00 20000 88 Using shared libraries o sakarina es ea A E Bee Se ee oe Re eee E 91 4 13 1 Building programs that use shared libraries 2 2 ee 91 4 13 2 Shared libraries for Haskell packages a 92 4 13 3 Shared libraries that export a C API naana aaa a 92 4 13 4 Finding shared libraries
8. The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 281 327 7 29 1 2 Building secure systems restricted IO Monads Systems such as information flow control security capability based security systems and DSLs for working with encrypted data etc can be built in the Haskell language simply as a library However they require guarantees about the properties of the Haskell language that aren t true in the general case where uses of functions like unsafePerformI0O are allowed Safe Haskell is designed to give users enough guarantees about the safety properties of compiled code so that such secure systems can be built As an example lets define an interface for a plugin system where the plugin authors are untrusted possibly malicious third parties We do this by restricting the plugin interface to pure functions or to a restricted IO monad that we have defined that only allows a safe subset of TO actions to be executed We define the plugin interface here so that it requires the plugin module Danger to export a single computation Danger runMe of type RIO where RIO is a new monad defined as follows Either of the following Safe Haskell pragmas would do LANGUAGE Trustworthy LANGUAGE Safe module RIO RIO runRIO rioReadFile rioWriteFile where Notice that symbol UnsafeRIO is not exported from this module newtype RIO a UnsafeRIO runRIO IO a instance Monad R
9. e NOINLINE k f means be willing to inline f until phase k but from phase k onwards do not inline it The same information is summarised here The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 264 327 Before phase 2 Phase 2 and later INLINE 2 No Yes INLINE 22 E Yes No NOINLINE 2 f No Maybe NOINLINE 2 f Maybe No INLINE f Yes Yes NOINLINE No No By Maybe we mean that the usual heuristic inlining rules apply if the function body is small or it is applied to interesting looking arguments etc Another way to understand the semantics is this e For both INLINE and NOINLINE the phase number says when inlining is allowed at all e The INLINE pragma has the additional effect of making the function body look small so that when inlining is allowed it is very likely to happen The same phase numbering control is available for RULES Section 7 23 7 22 7 LINE pragma This pragma is similar to C s 1ine pragma and is mainly for use in automatically generated Haskell code It lets you specify the line number and filename of the original code for example LINE 42 Foo vhs if you d generated the current file from something called Foo vhs and this line corresponds to line 42 in the original GHC will adjust its error messages to refer to the line file named in the
10. sum 22 ati lt gt Ink SUMISO ICE _ 7A Sas Shows holisst hok 2r I5 Hound noliec YE e T e Ione TE In the first argument of foldr namely _ In the expression foldr _a _b _c ln em EKeMMENCAKOIN Eos Sb s Suu se olcha a jo e KOISA AS ARTN Found hole _z with type Int In the second argument of foldr namely _ In the expression foldr _a _b _c In an equation Lor etm sum lt olek a ib Be Unbound identifiers with the same name are never unified even within the same function but always printed individually For example cons k i results in the following errors unbound as sake Found hole _x with type a Where a is a rigid type variable bound by the inferred type of cons a at unbound hs 1 1 Relevant bindings include cons a bound at unbound hs 1 1 In the first argument of namely _x In the expression _x _x mian equation efor eons Cons ase 6 un ouna ey nese sales Found hole _x with type a Arising from an undeclared identifier _x at unbound hs 1 13 14 Where a is a rigid type variable bound by the inferred type of cons a at unbound hs 1 1 Relevant bindings include cons a bound at unbound hs 1 1 In the second argument of namely _x In the expression _x _x a a quemricia er comas coma E 8 dK This ensures that an unbound identifier is never reported with a t
11. On systems with d11 style shared libraries the actual library loaded will be 1ib d11 Again GHCi will signal an error if it can t find the library GHCi can also load plain object files o or obj depending on your platform from the command line Just add the name the object file to the command line Ordering of 1 options matters a library should be mentioned before the libraries it depends on see Section 4 12 6 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 33 327 2 7 GHCi commands GHCi commands all begin with and consist of a single command name followed by zero or more parameters The command name may be abbreviated with ambiguities being resolved in favour of the more commonly used commands abandon Abandons the current evaluation only available when stopped at a breakpoint add module Add module s to the current target set and perform a reload Normally pre compiled code for the module will be loaded if available or otherwise the module will be compiled to byte code Using the x prefix forces the module to be loaded as byte code back Travel back one step in the history See Section 2 5 5 See also trace history forward break identifier module line column Seta breakpoint on the specified function or line and column See Section 2 5 1 1 browsel module Displays the identifiers exported by the module module which must be either
12. gt Int gt value intLookup This feature has been removed as it is now subsumed by the RULES pragma see Section 7 23 6 7 22 10 SPECIALIZE instance pragma Same idea except for instance declarations For example The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 267 327 instance Eq a gt Eq Foo a where SPECIALIZE instance Eq Foo Int Bar usual stuff The pragma must occur inside the where part of the instance declaration 7 22 11 UNPACK pragma The UNPACK indicates to the compiler that it should unpack the contents of a constructor field into the constructor itself removing a level of indirection For example data T T UNPACK Float UNPACK Float will create a constructor T containing two unboxed floats 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 Unpacking constructor fields should only be used in conjunction with 0 in order to expose unfoldings to the compiler so the reboxing can be removed as often as possible For example i 88 E gt loa ie ae seal PEZI aril ae see The compiler will avoid reboxing 1 and f2 by inlining on floats but only when O is on Any single constructor data is eligible for unpacking for example d
13. 127 327 opt module args specified with fplugin Flag Description Static Dynamic Reverse no link Omit linking dynamic split objs Split objects for libraries dynamic static Use static Haskell libraries dynamic threaded Use the threaded runtime dynamic debug Use the debugging runtime dynamic For linking this simply ticky implies debug see dynamic Section 5 8 Enable runtime event eventlog dynamic tracing T Do not generate a manifest name g file Windows only Do not embed the manifest fno embed 3 manifest in the executable Windows dynamic only Don t generate an import fno shared implib library for a DLL Windows dynamic only Set the install name via install_name passed to Apple s linker specifying the full install path of the dylib install library file Any libraries or a sa dynamic name path executables that link with it later will pick up that path as their runtime search location for it Darwin OS X only This instructs the linker to add all symbols not only used ones to the dynamic symbol table Currently Linux and rdynamic Windows MinGW32 only dynamic This is equivalent to using optl rdynamic on Linux and optl export all symbols on Windows 4 19 22 Plugin options Section 9 3 Flag Description Static Dynamic Reverse fpluginemoasie 10da pugin expore
14. GMap Same as previous item but also exports all the data constructors for GMap namely GMapEither e module GMap GMapKey empty lookup insert GMap Same as previous item e module GMap GMapKey empty lookup insert GMap Same as previous item Two things to watch out for e You cannot write GMapKey type GMap 1 e sub component specifications cannot be nested To specify GMap s data constructors you have to list it separately e Consider this example module X where data family D module Y where import X data instance D Int Dl D2 Module Y exports all the entities defined in Y namely the data constructors D1 and D2 but not the data family D That annoyingly means that you cannot selectively import Y selectively thus import Y D D1 D2 because Y does not export D Instead you should list the exports explicitly thus module Y D where or module Y module Y D where 7 7 4 2 Instances Family instances are implicitly exported just like class instances However this applies only to the heads of instances not to the data constructors an instance defines The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 216 327 7 7 5 Type families and instance declarations Type families require us to extend the rules for the form of instance heads which are given in Section 7 6 3 2 Specifically e Data type families may appear in
15. If you want to do the steps manually or are writing your own build system then there are certain conventions that must be followed Building a shared library that exports Haskell code to be used by other Haskell code is a bit more complicated than it is for one that exports a C API and will be used by C code If you get it wrong you will usually end up with linker errors In particular Haskell shared libraries must be made into packages You cannot freely assign which modules go in which shared libraries The Haskell shared libraries must match the package boundaries The reason for this is that GHC handles references to symbols within the same shared library or main executable binary differently from references to symbols between different shared libraries GHC needs to know for each imported module if that module lives locally in the same shared lib or in a separate shared lib The way it does this is by using packages When using dynamic a module from a separate package is assumed to come from a separate shared lib while modules from the same package or the default main package are assumed to be within the same shared lib or main executable binary Most of the conventions GHC expects when using packages are described in Section 4 9 8 In addition note that GHC expects the hi files to use the extension dyn_hi The other requirements are the same as for C libraries and are described below in particular the use of the flags dynamic f
16. OVERLAPPING C t where 7 23 Rewrite rules The programmer can specify rewrite rules as part of the source program in a pragma Here is an example RULES map map Rora Mi E E ss mejo e eo e mejo Ese ss w Use the debug flag ddump simpl stats to see what rules fired If you need more information then ddump rule firings shows you each individual rule firing and ddump rule rewrites also shows what the code looks like before and after the rewrite 7 23 1 Syntax From a syntactic point of view e There may be zero or more rules in a RULES pragma separated by semicolons which may be generated by the layout rule e The layout rule applies in a pragma Currently no new indentation level is set so if you put several rules in single RULES pragma and wish to use layout to separate them you must lay out the starting in the same column as the enclosing definitions RULES map map forall ig xes Map ue G xe map ToC xs map append forall f xs ys map f xs ys map f xs map f ys tay Furthermore the closing should start in a column to the right of the opening Each rule has a name enclosed in double quotes The name itself has no significance at all It is only used when reporting how many times the rule fired A rule may optionally have a phase control number see Section 7 22 6 5 immediately after the name of the rule Thus RULES map map 2 f
17. The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 73 327 Otherwise it behaves like ghc pkg list including options ghc pkg latest P Prints the latest available version of package P ghc pkg describe P Emit the full description of the specified package The description is in the form of an Installed PackagelInfo the same as the input file format for ghc pkg register See Section 4 9 9 for details If the pattern matches multiple packages the description for each package is emitted separated by the string on a line by itself ghc pkg field P field field Show just a single field of the installed package description for P Multiple fields can be selected by separating them with commas ghc pkg dot Generate a graph of the package dependencies in a form suitable for input for the graphviz tools For example to generate a PDF of the dependency graph ghc pkg dot tred dot Tpdf gt pkgs pdf ghc pkg dump Emit the full description of every package in the form of an InstalledPackagelInfo Multiple package descriptions are separated by the string on a line by itself This is almost the same as ghc pkg describe x except that ghc pkg dump is intended for use by tools that parse the results so for example where ghc pkg describe x will emit an error if it can t find any packages that match the pattern ghc pkg dump will simply emit nothing ghc pkg recache Re creates the
18. XNoGenerics XImplicitParams Enable Implicit Parameters Implies XFlexibleContexts and XFlexiblelnstances dynamic XNoImplicitParams XNoImplicitPrelude Don t implicitly import Prelude Implied by XRebindableSyntax dynamic XImplicitPrelude The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 115 327 Flag Description Static Dynamic Reverse XImpredicativeTy Enable impredicative types dans XNoImpredicativeT pes Implies XRankNTypes y ypes Enable incoherent XIncoherentInstan o XNoIncoherentInst instances Implies XOver dynamic ces ances lappingInstances XInstanceSigs Enable instance signatures dynamic XNoInstanceSigs s XNoInterruptible XInterruptibleFFI Enable interruptible FFI dynamic ERT hala Enable kind signatures Implied by XKindSignatures p y Mana dynamic XNoKindSignatures XTypeFamilies and XPolyKinds Enable lambda case i XLambdaCase dynamic XNoLambdaCase expressions XLiberalTypeSynon Enable liberalised type dynan XNoLiberalTypeSyn yms synonyms y onyms XMagicHash Allow aF as a posily dynamic XNoMagicHash z L A modifier on identifiers y A XMonadComprehensi Enable monad is XNoMonadComprehen ons comprehensions y sions Enable do not generalise local bindings Implied b XM
19. ab a gt 5 to class F a b gt C ab where type F a That is we represent every functional dependency FD al an gt b by an FD type family F al an anda superclass context equality F al an b essentially giving a name to the functional dependency In class instances we define the type instances of FD families in accordance with the class head Method signatures are not affected by that process 7 11 1 The Coercible constraint The constraint Coercible t1 t2 is similar to t1 t2 but denotes representational equality between t1 and t 2 in the sense of Roles Section 7 27 It is exported by Data Coerce which also contains the documentation More details and discussion can be found in the paper Safe Coercions 7 12 The Constraint kind Normally constraints which appear in types to the left of the gt arrow have a very restricted syntax They can only be e Class constraints e g Show a e Implicit parameter constraints e g x Int with the XImplicitParams flag e Equality constraints e g a Int with the XTypeFamilies or XGADTs flag With the XConstraintKinds flag GHC becomes more liberal in what it accepts as constraints in your program To be precise with this flag any type of the new kind Constraint can be used as a constraint The following things have kind Constraint e Anything which is already valid as a constraint without the flag saturated applications to type classes implicit parame
20. dynamic core2core core to core pass Show output from each 9 d 5 dverbose stg2stg STG to STG pass ynamic Print out each lion panses Print out each pass name as naaa 1t happens Show statistics for fast dfaststring stats dynamic string usage when finished The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 131 327 Flag Description Static Dynamic Reverse Report sites with rules that frule check could have fired but didn t dynamic Takes a string argument 4 19 27 Misc compiler options Flag Description Static Dynamic Reverse When compiling with jN make compile N modules dynamic in parallel fno hi version Don t complain about hi d x check file mismatches ERER g Ehistory siz Set simplification history diaas lt size Do not use the load store fno ghci history the GHCi command history dynamic from to ghci_history Turn off the GHCi sandbox fno ghci sandbox Meads Compiatons ate dynamic run in the main thread rather than a forked thread The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 132 327 Chapter 5 Profiling GHC comes with a time and space profiling system so that you can answer questions like why is my program so slow or why is my program using so much memory Profiling a program is a three step process 1
21. module Foo where import M x True les MiS I z pi seri Uses both disambiguation and punning e With XDisambiguateRecordFields you can use unqualified field names even if the corresponding selector is only in scope qualified For example assuming the same module M as in our earlier example this is legal module Foo where import qualified M Note qualified ok4 M MkS x n n 1 Unambiguous Since the constructor MkS is only in scope qualified you must name it M MkS but the field x does not need to be qualified even though M x is in scope but x is not In effect it is qualified by the constructor The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 173 327 7 3 23 Record puns Record puns are enabled by the flag XNamedFieldPuns When using records it is common to write a pattern that binds a variable with the same name as a record field such as asta s C fa g3 ini f C a a a Record punning permits the variable name to be elided so one can simply write f C a a to mean the same pattern as above That is in a record pattern the pattern a expands into the pattern a a for the same name a Note that e Record punning can also be used in an expression writing for example let a Lin da instead of let a 1 in C a a The expansion is purely syntactic so the expanded right hand side expression refers to the nearest enclosing variable that is
22. under them In an extreme case you can write all your time critical code in C and then just glue it together with Haskell Before you get too carried away working at the lowest level e g sloshing Mut ableByteArray s around your program you may wish to check if there are libraries that provide a Haskellised veneer over the features you want The separate libraries documentation describes all the libraries that come with GHC 7 1 Language options The language option flags control what variation of the language are permitted Language options can be controlled in two ways e Every language option can switched on by a command line flag X e g XTemplateHaskel11 and switched off by the flag XNo e g XNoTemplateHaskell e Language options recognised by Cabal can also be enabled using the LANGUAGE pragma thus LANGUAGE Template Haskell see Section 7 22 1 The flag fglasgow exts is equivalent to enabling the following extensions KConstrainedClassMethods XDe riveDataTypeable XDeriveFoldable XDeriveFunctor XDeriveGeneric XDeriveTraversable XEmptyDataDecls XExistentialQuantification XExplicitNamespaces XFlexibleContexts XFlexiblelnstances XForeignFunctionInterface XFunctionalDependencies XGeneralizedN wtypeDeriving XImplicitParams XKindSignatures XLiberalTypeSynonyms XMagicHash XMu ltiParamTypeClasses XParallelListComp XPatternGuards XPostfixOperators XRa
23. AA a 14 i If indexIntArray ba i ArrPare eal a2 Ud at lx o 32 121 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 266 327 Here is a recursive function that indexes arrays of type Arr e Consider a call to at type Int Int The second specialisation will fire and the specialised function will be inlined It has two calls to both at type Int Both these calls fire the first specialisation whose body is also inlined The result is a type based unrolling of the indexing function You can add explicit phase control Section 7 22 6 5 to SPECIALISE INLINE pragma just like on an INLINE pragma if you do so the same phase is used for the rewrite rule and the INLINE control of the specialised function T Warning you can make GHC diverge by using SPECIALISE INLINE on an ordinarily recursive function 7 22 9 2 SPECIALIZE for imported functions Generally you can only give a SPECIALIZE pragma for a function defined in the same module However if a function f is given an INLINABLE pragma at its definition site then it can subsequently be specialised by importing modules see Section 7 22 6 2 For example module Map lookup blah blah where lookup Ord key gt key a gt key gt Maybe a lookup INLINABLE lookup module Client wher import Map lookup Glace al we clersyias Joy Orxecl AS
24. NEAL e ez integer gmp 0 1 0 0 mel 0 2 olda locale iTo old time 1 0 0 pretty 1 OnO process m Orm randon IOMO sus 010 Svo ON MORNO template haskell 2 4 0 0 terminto OMori time 1 1 4 ame A Se AO Uers String Osa Ore il An installed package is either exposed or hidden by default Packages hidden by default are listed in parentheses eg lang 1 0 or possibly in blue if your terminal supports colour in the output of ghc pkg list Command line flags described below allow you to expose a hidden package or hide an exposed one Only modules from exposed packages may be imported by your Haskell code if you try to import a module from a hidden package GHC will emit an error message If there are a multiple exposed versions of a package GHC will prefer the latest one Additionally some packages may be broken that is they are missing from the package database or one of their dependencies are broken in this case these packages are excluded from the default set of packages Note if you re using Cabal then the exposed or hidden status of a package is irrelevant the available packages are instead determined by the dependencies listed in your cabal specification The exposed hidden status of packages is only relevant when using ghc or ghci directly Similar to a package s hidden status is a package s trusted status A package can be either trusted or not trusted distrusted By default packages are distrusted This prope
25. To get the annotations of a single binder you can use getAnnotations and specify the proper type Here s an example that will print out the name of any top level non recursive binding with the SomeAnn annotation LANGUAGE DeriveDataTypeable module SayAnnNames Plugin plugin SomeAnn where import GhcPlugins import Control Monad unless import Data Data data SomeAnn SomeAnn deriving Data Typeable plugain 3 Uma plugin defaultPlugin installCoreToDos install install CommandLineOption gt CoreToDo gt CoreM CoreToDo install todo do reinitializeGlobals return CoreDoPluginPass Say name pass todo pass ModGuts gt CoreM ModGuts pass g do dflags lt getDynFlags mapM_ printAnn dflags g mg_binds g gt gt return g where printAnn DynFlags gt ModGuts gt CoreBind gt CoreM CoreBind printAnn dflags guts bndr NonRec b _ do anns lt annotationsOn guts b CoreM SomeAnn unless null anns putMsgS Annotated binding found showSDoc dflags ppr b return bndr printAnn _ _ bndr return bndr annotationsOn Data a gt ModGuts gt CoreBndr gt CoreM a The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 301 327 annotationsOn guts bndr do anns lt getAnnotations deserializeWithData guts return lookupWithDefaultUFM anns varUnique bndr Please see the GHC API documentation for more about
26. _4 then to a dictionary yielding the actual addition function that we will use subsequently We play the exact same game with the non standard class method eonim e Waste sy as Emos mie ig wired Imro Tis compiler Lies edilo 38 A Ni 1it t4Hb let Cl Clr s E Zo NI ds d4Qz I 2 E Ml SS cls coy CIF 24 is just the literal Int 2 it reflects the fact that GHC defines data Int I Int where Int is the primitive unboxed type see relevant info about unboxed types elsewhere The after I indicates that this is a saturated application Cit toe me Cece Const tetos Los mor Jere lali applied Skip2 eodian gt EA IE skip2 t3Ja m rlH4 gt lert ds 0100 2 NI ds d400 let dsrd AO A NI ds d4QY t4Hg m r1H4 1it t4Hb in skip2 t3Ja ds d4QY ala Ll 4 mill ds 0100 end CoRec Spas ua It s just a simple functional language is an unregisterised trademark of Peyton Jones Enterprises plc 4 19 Flag reference This section is a quick reference for GHC s command line flags For each flag we also list its static dynamic status see Sec tion 4 3 and the flag s opposite if available 4 19 1 Verbosity options More details in Section 4 6 Flag Description Static Dynamic Reverse verbose mode equivalent to v3 v dynamic The Glorious Glasgow Ha
27. boot is empty don t link it but it is very useful when using a Makefile to record when the A hi boot was last brought up to date see Section 4 7 11 The hi boot generated by compiling a hs boot file is in the same machine generated binary format as any other GHC generated interface file e g B hi You can display its contents with ghe show iface If you specify a directory for interface files the ohidir flag then that affects hi boot files too e If hs boot files are considered distinct from their parent source files and if a SOURCE import is considered to refer to the hs boot file then the module import graph must have no cycles The command ghc M will report an error if a cycle is found e A module M that is SOURCE imported in a program will usually also be ordinarily imported elsewhere If not ghc make automatically adds M to the set of modules it tries to compile and link to ensure that M s implementation is included in the final program A hs boot file 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 s that import A recursively A hs boot file is written in a subset of Haskell e The module header including the export list and import statements are exactly as in Haskell and so are
28. falc pe lt iba peso Dies a rebum bc K As usual the meta variables b c etc can be arbitrary patterns In general the statement rec ss is desugared to the statement vs lt mfix vs gt do ss return vs where vs is a tuple of the variables bound by ss Note in particular that the translation for a rec block only involves wrapping a call to mf ix it performs no other analysis on the bindings The latter is the task for the mdo notation which is described next 7 3 12 2 The mdo notation A rec block tells the compiler where precisely the recursive knot should be tied It turns out that the placement of the recursive knots can be rather delicate in particular we would like the knots to be wrapped around as minimal groups as possible This process is known as segmentation and is described in detail in Secton 3 2 of A recursive do for Haskell Segmentation improves polymorphism and reduces the size of the recursive knot Most importantly it avoids unnecessary interference caused by a fundamental issue with the so called right shrinking axiom for monadic recursion In brief most monads of interest IO strict state etc do not have recursion operators that satisfy this axiom and thus not performing segmentation can cause unnecessary interference changing the termination behavior of the resulting translation Details can be found in Sections 3 1 and 7 2 2 of Value Recursion in Monadic Computations The mdo notation re
29. functions values that are small enough thus avoiding the call overhead and possibly exposing other more wonderful optimisations GHC has a set of heuristics tuned over a long period of time using many benchmarks that decide when it is beneficial to inline a function at its call site The heuristics are designed to inline functions when it appears to be beneficial to do so but without incurring excessive code bloat If a function looks too big it The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 262 327 won t be inlined and functions larger than a certain size will not even have their definition exported in the interface file Some of the thresholds that govern these heuristic decisions can be changed using flags see Section 4 10 2 Normally GHC will do a reasonable job of deciding by itself when it is a good idea to inline a function However sometimes you might want to override the default behaviour For example if you have a key function that is important to inline because it leads to further optimisations but GHC judges it to be too big to inline The sledgehammer you can bring to bear is the INLINE pragma used thusly E cue ayo FG dam gt Sieresigve gt Eko Denise INLINE key_function The major effect of an INLINE pragma is to declare a function s cost to be very low The normal unfolding machinery will then be very keen to inline it However an INLIN
30. mkPat b x y would fail with x and y being out of scope The difference in treatment of outermost and nested pattern splices is because outermost splices are run at compile time GHC can then use the result of running the splice when analyzing the expressions within the pattern s scope Nested splices on the other hand are not run at compile time they are run when the bracket is spliced in sometime later Since nested pattern splices may refer to local variables there is no way for GHC to know at splice compile time what variables are bound so it binds none The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 246 327 e A pattern quasiquoter may generate binders that scope over the right hand side of a definition because these binders are in scope lexically For example given a quasiquoter haske11 that parses Haskell in the following code the y in the right hand side of f refers to the y bound by the haske11 pattern quasiquoter not the top level y 7 Ps RO y 7 i 28 dae gt Moe gt Tale a Ny SS AS syma Top level declaration splices break up a source file into delcaration groups A declaration group is the group of declarations created by a top level declaration splice plus those following it down to but not including the next top level declaration splice The first declaration group in a module includes all top level definitions down to but not including the first top level
31. show modules 38 show packages 38 show paths 38 showi language 38 isprint 38 istep 38 steplocal 38 stepmodule 38 trace 38 type 38 undef 38 unset 38 _ GLASGOW_HASKELL_LLVM__ 87 _ GLASGOW_HASKELL_PATCHLEVEL1__ 86 _ GLASGOW_HASKELL_PATCHLEVEL2__ 86 __GLASGOW_HASKELL_TH_ 87 __GLASGOW_HASKELL _ 2 86 _ PARALLEL_HASKELL__ 87 A allocation area chunk size 98 allocation area size 98 amp 61 ANN 296 297 ANN module 297 ANN type 297 apparently erroneous do binding warning 66 applicative monad proposal 61 arguments command line 45 ASCII 50 Assertions 258 author package specification 76 auto package specification 76 B Bang patterns 256 binds unused 65 bugs reporting 2 C C calls function headers 293 C code generator 84 C pre processor options 86 CAFs in GHCi 39 category package specification 76 cc options package specification 77 Char size of 317 code coverage 143 command line arguments 45 compacting garbage collection 98 compiled code in GHCi 14 compiler problems 303 compiling faster 148 Concurrent Haskell using 93 CONLIKE 263 consistency checks 107 Constant Applicative Form see CAFs constructor fields strict 83 context implicit quantification 65 copyright package specification 76 Core syntax how to read 107 cost centres automatically inserting 135 cost centre profiling 132 cpp pre processing with 86 Creating a
32. w True TALES ala data T MkT Int Bool a Mer aa Selec alan joy Mia ss 1 Man Tllegal b 7 3 25 Local Fixity Declarations A careful reading of the Haskell 98 Report reveals that fixity declarations infix infixl and infixr are permitted to appear inside local bindings such those introduced by let and where However the Haskell Report does not specify the semantics of such bindings very precisely In GHC a fixity declaration may accompany a local binding The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 175 327 Lo ie gt oes akigge aksscie S ES in and the fixity declaration applies wherever the binding is in scope For example in a let it applies in the right hand sides of other 1et bindings and the body of the 1etC Or in recursive do expressions Section 7 3 12 the local fixity declarations of a let statement scope over other statements in the group just as the bound name does Moreover a local fixity declaration must accompany a local binding of that name it is not possible to revise the fixity of name bound elsewhere as in lee imkize J ain ogs Because local fixity declarations are technically Haskell 98 no flag is necessary to enable them 7 3 26 Import and export extensions 7 3 26 1 Hiding things the imported module doesn t export Technically in Haskell 2010 this is illegal module A f where f True module B where import A hiding
33. 327 data U MkU U gt Bool Gussel U gt Bool russel u MkU p not pu BO Ol x russel MkU russel We have never found another class of programs other than this contrived one that makes GHC diverge and fixing the problem would impose an extra overhead on every compilation So the bug remains un fixed There is more background in Secrets of the GHC inliner e On 32 bit x86 platforms when using the native code generator the fexcess precision option is always on This means that floating point calculations are non deterministic because depending on how the program is compiled optimisation settings for example certain calculations might be done at 80 bit precision instead of the intended 32 bit or 64 bit precision Floating point results may differ when optimisation is turned on In the worst case referential transparency is violated because for example let x E1 in E2 can evaluate to a different value than E2 E1 x One workaround is to use the msse2 option see Section 4 16 which generates code to use the SSE2 instruction set instead of the x87 instruction set SSE2 code uses the correct precision for all floating point operations and so gives deterministic results However note that this only works with processors that support SSE2 Intel Pentium 4 or AMD Athlon 64 and later which is why the option is not enabled by default The libraries that come with GHC are probably built without th
34. 54 imports unused 65 improvement code 78 include dirs package specification 77 includes package specification 77 incomplete patterns warning 63 incomplete record updates warning 63 INLINE 261 INLINE pragma 262 inlining controlling 83 installer detection 90 Int size of 317 interactive see GHCi interactive mode 46 interface files 50 interface files finding them 51 interface files options 53 intermediate files saving 53 intermediate passes output 105 interpreter see GHCi invoking GHCi 32 it 22 L LANGUAGE pragma 260 language option 152 language GHC 152 Latin 1 50 ld options 88 1d options package specification 77 lhs suffix 46 libdir 47 libraries with GHCi 32 library dirs package specification 77 license file package specification 76 LINE pragma 264 linker options 88 linking Haskell libraries with foreign code 89 lint 107 list comprehensions generalised 165 parallel 165 LLVM code generator 84 M machine specific options 95 mailing lists Glasgow Haskell maintainer package specification 76 make 57 make and recompilation 50 make mode 46 Makefile dependencies 58 Makefiles avoiding 47 MallocFailHook 97 manifest 90 matches unused 65 mdo 176 memory using less heap 151 methods missing 63 MIN_VERSION_GLASGOW_HASKELL 86 MINIMAL 261 missing fields warning 63 missing import lists warning 63 missing methods warning 63 mode option
35. CAF Main main Main main g Main fib Main main f Main alo Main no 102 128 120 110 108 204 20 208 205 206 entries PPS Sa eS TANS ll 26925 Stime fe Ss eS ere ees oS eae e fey S 1s Se toto tooo Salloc 1 ee ae ee Me er 1 te S eS ea ee lt 2 Ne Stime 100 100 100 100 100 Sas aca e ee S alloc SOON 100 LOO Jon 997 O Wey AA O ey O O O e The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 134 327 Now although we had two calls to ib in the program it is immediately clear that 1t was the call from which took all the time The functions f and g which are defined in the where clause in main are given their own cost centres main f and main g respectively The actual meaning of the various columns in the output is entries The number of times this particular point in the call tree was entered individual time The percentage of the total run time of the program spent at this point in the call tree individual alloc The percentage of the total memory allocations excluding profiling overheads of the program made by this call inherited time The percentage of the total run time of the program spent below this point in the call tree inherited alloc The percentage of the total memory allocations excluding profiling overheads of the program made by this call and all of its sub calls In addition you can u
36. Private Declare Function Adder Lib Adder d11 Alias adder 8 _ ByVal x As Long ByVal y As Long As Long Private Declare Sub HsStart Lib Adder dl1 Private Declare Sub HsEnd Lib Adder dl1 Private Sub Document_Close The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 313 327 HsEnd End Sub Private Sub Document_Open HsStart End Sub Public Sub Test sigition Volz ar 6 AO ASIA ELO End Sub This example uses the Document_Open Close functions of Microsoft Word but provided HsSt art is called before the first function and HsEnd after the last then it will work fine 12 6 2 2 Using from C An example of using Adder d11 from C is Tester cpp include HsFFI h include Adder_stub h include lt stdio h gt extern C vola ASS Lars MOL AS BDO int main HSA nee can now safely call functions from the DLL cia WIA ae O ala arclolsis 112 S E sn ai return 0 This can be compiled and run with ghc o tester Tester cpp Adder dll a S tester la B 17 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 314 327 Chapter 13 Known bugs and infelicities 13 1 Haskell standards vs Glasgow Haskell language non compliance This section lists Glasgow Haskell infelicities in its implementation of Haskell 98 and Haskell 2010 See also the when things go wrong section Chapt
37. See also fwarn typed holes fwarn partial type signatures Determines whether the compiler reports holes in partial type signatures as warn ings Has no effect unless XPartialTypeSignatures is enabled which controls whether errors should be generated for holes in types or not See Section 7 15 This warning is on by default fhelpful errors When a name or package is not found in scope make suggestions for the name or package you might have meant instead This option is on by default fwarn unrecognised pragmas Causes a warning to be emitted when a pragma that GHC doesn t recognise is used As well as pragmas that GHC itself uses GHC also recognises pragmas known to be used by other tools e g OPTIONS _ HUGS and DERIVE This option is on by default fwarn pointless pragmas Causes a warning to be emitted when GHC detects that a module contains a pragma that has no effect This option is on by default fwarn warnings deprecations Causes a warning to be emitted when a module function or type with a WARNING or DEPRECATED pragma is used See Section 7 22 4 for more details on the pragmas This option is on by default fwarn amp Causes a warning to be emitted when a definition is in conflict with the AMP Applicative Monad proosal namely 1 Instance of Monad without Applicative 2 Instance of MonadPlus without Alternative 3 Custom definitions of join pure lt gt This option is on by def
38. The change also applies to Template Haskell splices such as t Ord a gt al which should be written as t forall a Ord a gt al e Instance contexts inferred while processing deriving directives attached to data and newt ype declarations now forbid equality constraints This is a regression in obscure cases but it will yield better error messages in more common cases Users caught by the regression can simply use standalone deriving where you specify the context yourself 1 5 2 2 Compiler e GHC now checks that all the language extensions required for the inferred type signatures are explicitly enabled This means that if any of the type signatures inferred in your program requires some language extension you will need to enable it The motivation is that adding a missing type signature inferred by GHC should yield a program that typechecks Previously this was not the case This is a breaking change Code that used to compile in the past might fail with an error message requiring some particular language extension most likely XTypeFamilies XGADTs or XFlexibleContexts e The solvers for both type family reductions and Coercible instances have been improved This should lead to faster compilation of type family heavy code and more Coercible instances to be found However some bugs remain see Known Bugs below e fwarn tabs warning flag is turned on by default with this release of GHC It can be suppressed either by us
39. The special family distinguishes family from standard type declarations The result kind annotation is optional and as usual defaults to if omitted An example is type family Elem c Parameters can also be given explicit kind signatures if needed We call the number of parameters in a type family declaration the family s arity and all applications of a type family must be fully saturated w r t to that arity This requirement is unlike ordinary type synonyms and it implies that the kind of a type family is not sufficient to determine a family s arity and hence in general also insufficient to determine whether a type family application is well formed As an example consider the following declaration EOS emaily 12 alo BY ee gt 6 P S vel as 2 ROA ASS MO Sir MI as s x S E 35 Given this declaration the following are examples of well formed and malformed types ID Casi iat OL ialinole gt lt T Chaar ae Bool OKI KIDO s PEMORBOON WRONG kind mismatch in the first argument F Bool WRONG unsaturated application The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 210 327 7 7 2 2 Type instance declarations Instance declarations of type families are very similar to standard type synonym declarations The only two differences are that the keyword t ype is followed by instance and that some or all of the type arguments can be non variable types but may not contain forall
40. XRelaxedPolyRec GHC only insists that the type signatures of a refined group have identical type signatures in practice this means that only variables bound by the same pattern binding must have the same context For example this is fine E a gt a gt BOOL Ezz x x true a 88 Orol a gt a gt BOOL g y y Se y E Teve 7 13 9 3 Let generalisation An ML style language usually generalises the type of any let bound or where bound variable so that it is as polymorphic as possible With the flag XMonoLocalBinds GHC implements a slightly more conservative policy using the following rules e A variable is closed if and only if the variable is let bound one of the following holds x the variable has an explicit type signature that has no free type variables or its binding group is fully generalised see next bullet e A binding group is fully generalised if and only if each of its free variables is either imported or closed and The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 238 327 the binding is not affected by the monomorphism restriction Haskell Report Section 4 5 5 For example consider IE se OR ap GL gx let hy f yx 2 k z zt x sig a E Here f is generalised because it has no free variables and its binding group is unaffected by the monomorphism restriction and hence f is closed The same reasoning applies to g except that it has one
41. _hsc h C header _hsc c C file The C program is compiled using the Haskell compiler This provides the include path to HSFFI h which is automatically included into the C program 11 2 2 Input syntax All special processing is triggered by the operator To output a literal write it twice Inside string literals and comments characters are not processed A is followed by optional spaces and tabs an alphanumeric keyword that describes the kind of processing and its arguments Arguments look like C expressions separated by commas they are not written inside parens They extend up to the nearest unmatched or orto the end of line if it occurs outside any xx andis not preceded by a backslash Backslash newline pairs are stripped In addition stuff is equivalent to stuff except that it s self delimited and thus needs not to be placed at the end of line or in some brackets Meanings of specific keywords include lt file h gt include file h The specified file gets included into the C program the compiled Haskell file and the C header lt HsFFI h gt is included automatically define name define name value undef name Similar to include Note that includes and defi nes may be put in the same file twice so they should not assume otherwise let name parameters definition Defines a macro to be applied to the Haskell source Parameter names are comma sep
42. a string literal has type IsString a gt a This means that the usual string syntax can be used e g for ByteString Text and other variations of string like types String literals behave very much like integer literals i e they can be used in both expressions and patterns If used in a pattern the literal with be replaced by an equality test in the same way as an integer literal is The class IsStringis defined as class IsString a where ROMANO a The only predefined instance is the obvious one to make strings work as usual instance IsString Char where fromString cs cs The class IsSt ring is not in scope by default If you want to mention it explicitly for example to give an instance declaration for it you can import it from module GHC Exts Haskell s defaulting mechanism Haskell Report Section 4 3 4 is extended to cover string literals when KOverloadedStr ings is specified Specifically e Each type ina default declaration must be an instance of Num or of IsSt ring e Ifno default declaration is given then it is just as if the module contained the declaration default Integer Doub le String e The standard defaulting rule is extended thus defaulting applies when all the unresolved constraints involve standard classes or IsString and at least one is a numeric class or IsSt ring So for example the expression length foo will give rise to an ambiguous use of IsString a0 which because of the above
43. cpp is not friendly to string gaps In other words strings such as the following armo IN yny don t work with cpp 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 4 12 4 Options affecting a Haskell pre processor F A custom pre processor is run over your Haskell source file only if the F option is given Running a custom pre processor at compile time is in some settings appropriate and useful The F option lets you run a pre processor as part of the overall GHC compilation pipeline which has the advantage over running a Haskell pre processor separately in that it works in interpreted mode and you can continue to take reap the benefits of GHC s recompilation checker The pre processor is run just before the Haskell compiler proper processes the Haskell input but after the literate markup has been stripped away and possibly the C pre processor has washed the Haskell input Use pgmF cmd to select the program to use as the preprocessor When invoked the cmd pre processor is given at least three arguments on its command line the first argument is the name of the original source file the second is the name of the file holding the input and the third is the name of the file where cmd should write its output to Additional
44. de fault 32 fmax relevant binds n The type checker sometimes displays a fragment of the type environment in error messages but only up to some maximum number set by this flag The default is 6 Turning it off with fno max relevant bindings gives an unlimited number Syntactically top level bindings are also usually excluded since they may be numerous but fno max relevant bindings includes them too fmax simplifier iterations n Sets the maximal number of iterations for the simplifier Defult 4 fmax worker args n Ifa worker has that many arguments none will be unpacked anymore default 10 fno opt coercion Turn off the coercion optimiser fno pre inlining Turn off pre inlining fno state hack Turn off the state hack whereby any lambda with a State token as argument is considered to be single entry hence it is considered OK to inline things inside it This can improve performance of IO and ST monad code but it runs the risk of reducing sharing fomit interface pragmas Tells GHC to omit all inessential information from the interface file generated for the module being compiled say M This means that a module importing M will see only the types of the functions that M exports but not their unfoldings strictness info etc Hence for example no function exported by M will be inlined into an importing module The benefit is that modules that import M will need to be recompiled less often only when M s exports cha
45. dynamic dyno Set the output path for the dynamically linked objects dynamic dynosuf Set the output suffix for dynamic object files dynamic dynload Selects one of a number of modes for finding shared libraries at runtime dynamic framework name On Darwin OS X iOS only link in the framework name This option corresponds to the framework option for Apple s Linker dynamic framework path name On Darwin OS X iOS only add dir to the list of directories searched for frameworks This option corresponds to the F option for Apple s Linker dynamic 11ib Link in library 1ib dynamic Ldir Add dir to the list of directories searched for libraries dynamic main is Set main module and function dynamic mk d11 DLL creation mode Windows only dynamic no hs main Don t assume this program contains main dynamic rtsopts rtsopts none some all Control whether the RTS behaviour can be tweaked via command line flags and the GHCRTS environment variable Using none means no RTS flags can be given some means only a minimum of safe options can be given the default and all or no argument at all means that all RTS flags are permitted dynamic with rtsopts opts Set the default RTS options to opts dynamic The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2
46. ee ee 149 6 3 Smaller producing a program that is smaller e 151 6 4 Thriftier producing a program that gobbles less heap Space o e 151 7 GHC Language Features 152 7 1 Language options e fn owe es wee bw ek ee eae a eae ee ee ew A ee ae 152 7 2 Unboxed types and primitive operations oaoa ee 152 72M Unboxed types 2 2s eek ete dt PEt ba teed ebb eS RES eee Ss 8 153 7 2 2 lUnboxed tuples saos seee a e aa al e A 154 T 3 Syntactic extensions cs sora ep OR e a A lr A Pewee ES ee on a ee e 154 Tal Unicode syntax s osm eea o Ht bee id he BPS ed 154 132 Th magic hash 23 000 d e e a Ree a e ea Aa 155 T33 Negative literals sosega peaga soa ee eee a E wee ee a a 155 7 3 4 Fractional looking integer literals 2 ooa aaa 155 133 Binary integer literalS e ses dexi nenia eS Ee a ee 155 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 x 7 4 7 3 0 Hierarchical Modules ooo pad eee ee rai a o oS 156 137 Pattermpuards 4 2 24 rra di EPS SES ears e 156 7 3 8 VIEW pattems ocre Ge Be Sw ee we Sk OE oe a 157 139 Patteri synonyms s e e csa e a hoe a ee eee bea ee 159 7 3 9 1 Syntax and scoping of pattern synonyms soaa e 160 7 3 9 2 Import and export of pattern synonyms s eoa e 160 7 3 9 3 Typing of pattern synonyms soaa a 161 7 3 9 4 Matching of pattern synonyms a 162 TINO DEC pattems e a eee e A A EA e 163 7 3 11 Trad
47. el f view gt B p3 p4 e2 The current notion of when two view pattern expressions are the same is very restricted it is not even full syntactic equality However it does include variables literals applications and tuples e g two instances of view hi there will be collected However the current implementation does not compare up to alpha equivalence so two instances of x view x gt y will not be coalesced 7 3 9 Pattern synonyms Pattern synonyms are enabled by the flag XPatternSynonyms which is required for defining them but not for using them More information and examples of view patterns can be found on the Wiki page Pattern synonyms enable giving names to parametrized pattern schemes They can also be thought of as abstract constructors that don t have a bearing on data representation For example in a programming language implementation we might represent types of the language as follows data Type App String Type Here are some examples of using said representation Consider a few types of the Type universe encoded like this Mero Yas jci T2 2 el ee ot Noy icine f alte App Maybe App Int Maybe Int This representation is very generic in that no types are given special treatment However some functions might need to handle some known types specially for example the following two functions collect all argument types of nested arrow types and recognize the Int type respec
48. fsimplifier phases 81 fspec constr 81 fspec constr count 82 fspec constr threshold 82 fspecialise 82 fstatic argument transformation 82 fstrictness before 82 funbox small strict fields 83 funbox strict fields 83 funfolding creation threshold 83 funfolding dict discount 83 funfolding fun discount 83 funfolding keeness factor 83 funfolding use threshold 83 funfolding use thresholdO option 151 fvia C 84 fwarn amp 61 fwarn auto orphans 64 fwarn context quantification 65 fwarn deprecated flags 61 fwarn dodgy exports 62 fwarn dodgy foreign imports 62 fwarn dodgy imports 62 fwarn duplicate constraints 62 fwarn duplicate exports 62 fwarn empty enumerations 62 fwarn hi shadowing 62 fwarn identities 62 fwarn implicit prelude 62 fwarn import lists 63 fwarn incomplete patterns 63 fwarn incomplete record updates 63 fwarn incomplete uni patterns 63 fwarn inline rule shadowing 66 fwarn lazy unlifted bindings 62 fwarn missing exported sigs 64 fwarn missing fields 63 fwarn missing local sigs 64 fwarn missing methods 63 fwarn missing signatures 63 fwarn missing signatures option 149 fwarn monomorphism restriction 64 fwarn name shadowing 64 fwarn orphans 64 fwarn overflowed literals 62 fwarn overlapping patterns 64 fwarn partial type signatures 61 fwarn pointless pragmas 61 fwarn tabs 64 fwarn type defaults 64 fwarn typed holes 61 fwarn un
49. gt 2 Just k f y fwarn incomplete record updates The function f below will fail when applied to Bar so the compiler will emit a warning about this when fwarn incomplete record updates is enabled data Foo Foo x 12 Int Bar ic 28 TOG gt TOG E foo foo x 6 This option isn t enabled by default because it can be very noisy and it often doesn t indicate a bug in the program fwarn missing fields This option is on by default and warns you whenever the construction of a labelled field constructor isn t complete missing initializers for one or more fields While not an error the missing fields are initialised with bottoms it is often an indication of a programmer error fwarn missing import lists This flag warns if you use an unqualified import declaration that does not explic itly list the entities brought into scope For example module M where lore dE ALTON NG import qualified Z D ee SS E SE The fwarn import 1lists flag will warn about the import of Y but not X If module Y is later changed to export say f then the reference to f in M will become ambiguous No warning is produced for the import of Z because extending Z s exports would be unlikely to produce ambiguity in M fwarn missing methods This option is on by default and warns you whenever an instance declaration is missing one or more methods and the corresponding class declaration has no default declaration for them T
50. gt gt gt le gt data t5 a Ug ida 21 where NO kind is inferred data T6 ab where NO kind is inferred e For a class every type variable must be annotated with a kind e For a type synonym every type variable and the result type must all be annotated with kinds TE Sil er 68 Je et 8 fe Yes A Oe eile es E Ie type S2 a k a INO kind is inferred us SS e 28 Ik Dios El INO kind is inferred Note that in S2 and S3 the kind of the right hand side is rather apparent but it is still not considered to have a complete signature no inference can be done before detecting the signature e An open type or data family declaration always has a complete user specified kind signature un annotated type variables default to kind data family Dla Dil eg gt e datar amily RD Z2 ce seks DA 8 Hora ko k gt e clica seem IBS el 28 de 88 se D9 s rorall k AE wS Emu ly Sl a ee de gt gt Sil gs scored ik ik gt class C a where 8 Ik gt Compicicaalinc type AT ab IND 98 E In the last example the variable a has an implicit kind variable annotation from the class declaration It keeps its polymorphic kind in the associated type declaration The variable b however gets defaulted to x e A closed type familey has a complete signature when all of its type variables are annotated and a return kind with a top level is supplied 7 8 4 Kind inference in
51. has no scope TA os S9 lo gt o Means forall bo gt TL WS 88 W E Means forall a Ta e A constructor signature may mention type class constraints which can differ for different constructors For example this is fine data T a where i ge ma b b gt b gt T Ip Ta sa elbow er lx Oo e el gt re When pattern matching these constraints are made available to discharge constraints in the body of the match For example 2 pe 1 A gt SECUN i Wil xe yy sey yes otherwise no i 12 15 show a The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 185 327 Note that f is not overloaded the Eq constraint arising from the use of is discharged by the pattern match on T1 and similarly the Show constraint arising from the use of show e Unlike a Haskell 98 style data type declaration the type variable s in the data Set a where header have no scope Indeed one can write a kind signature instead data Set k gt where or even a mixture of the two clasica Bar ea 28 2 gt 2 gt mai The type variables 1f given may be explicitly kinded so we could also write the header for Foo like this data Bar a b x gt where e You can use strictness annotations in the obvious places in the constructor type data Term a where Lit B98 Mine gt tewm Iie TE BR Tera BooM gt Mesa a gt Term a gt Term a Pair
52. in error messages and in GHCi Using fprint explicit foralls makes GHC print explicit forall quantification at the top level of a type normally this is suppressed For example in GHCi ghci gt let f x x cielo Sit E i 88 2 a caecis geet iWwioMeLihe Skgollaeie ie eeu IES gnc O MI a gt a However regardless of the flag setting the quantifiers are printed under these circumstances e For nested foralls e g Ghiei gi EOS abusar Gac THEUNS forell s Ebc ol 6 2 gt 2 e If any of the quantified type variables has a kind that mentions a kind variable e g ghci gt i Data Type Equality sym Data Type Equality sym forall z He BOX da ss k o B3 kio al Dagar hy perm E qual Datan ype eea aa T Defined in Data Type Equality Using fprint explicit kinds makes GHC print kind arguments in types which are normally suppressed This can be important when you are using kind polymorphism For example ghci gt set XPolyKinds ghci gt data T a MkT caera gic MRI Mke forall k ty BOX ta o Eb Ea Ginsu eset Horta go lali itera clas ge Miki MET g toral k 33 B a s9 kje Lk a The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 50 327 ferror spans Causes GHC to emit the full source span of the syntactic entity relating to an error message Normally GHC emits the source location of the start of the syntactic entity only For example
53. l E to ML El Mil UL Leaf Meta information data DlUserTree data C1_0UserTree data C1_lUserTree instance Datatype DlUserTree wher datatypeName _ UserTree moduleName _ Main instance Constructor Cl_0UserTree where conName _ Node instance Constructor C1_lUserTree where conName _ Leaf This representation is generated automatically ifa deriving Generic clause is attached to the datatype Standalone deriving can also be used 7 26 2 Writing generic functions A generic function is defined by creating a class and giving instances for each of the representation types of GHC Generics As an example we show generic serialization data Bin O I class GSerialize f where Gone 8 se EL gt Bilal instance GSerialize Ul wher The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 275 327 apura instanc GSerialize a GSerialize b gt GSerializ a b where gious Fe 883 y goue x amr gore y instanc GSerialize a GSerialize b gt GSerializ a b where cial bil gt E Jout 2 Gone RL 5 2 8 joe 5 lt instanc GSerialize a gt GSerializ M1 i c a where Gjate AMIL s Gjate e instanc Serialize a gt GSerializ K1 i a where cjut MEL 52 joie xX Typically this class will not be exported as it only makes sense to have instances for the representation types 7 26 3 Generic defaults The only thing lef
54. let The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 308 327 def e Custom constructs The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 309 327 Chapter 12 Running GHC on Win32 systems 12 1 Starting GHC on Windows platforms The installer that installs GHC on Win32 also sets up the file suffix associations for hs and Ihs files so that double clicking them starts ghci Be aware of that ghe and ghci do require filenames containing spaces to be escaped using quotes e ghe bin ghci c Program Files Haskell Project hs If the quotes are left off in the above command ghci will interpret the filename as two c Program and Files Haskell Project hs 12 2 Running GHCi on Windows We recommend running GHCi in a standard Windows console select the GHCi option from the start menu item added by the GHC installer or use Start gt Run gt cmd to get a Windows console and invoke ghci from there as long as it s in your PATH If you run GHCi in a Cygwin or MSYS shell then the Control C behaviour is adversely affected In one of these environments you should use the ghcii sh script to start GHCi otherwise when you hit Control C you 1l be returned to the shell prompt but the GHCi process will still be running However even using the ghcii sh script if you hit Control C then the GHCi process will be killed immediately rather than letting
55. lt tale 2 clo se lt 1 10 y lt fle 62K return x y return x y e Group statements as with XTransformListComp amp lt Ml i 274 317 asa Groug by wWisalnG CEC bc Cuowjomalicla x x lt 1 1 2 2 3 Basa groria islas myeros e Parallel statements as with XParallelListComp sen amp lt Mo 107 7 lt O The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 168 327 Parallel statements are translated using the mzip function which requires a MonadZip instance defined in Control Monad Zip COMES lt maio clo x ON return x tdo y lt 1i 20 return y return x y All these features are enabled by default if the MonadComprehensions extension is enabled The types and more detailed examples on how to use comprehensions are explained in the previous chapters Section 7 3 14 and Section 7 3 13 In general you just have to replace the type a with the type Monad m gt m a for monad comprehensions Note Even though most of these examples are using the list monad monad comprehensions work for any monad The base package offers all necessary instances for lists which make MonadComprehensions backward compatible to built in trans form and parallel list comprehensions More formally the desugaring is as follows We write D e QJ to mean the desugaring of the monad comprehension e Ql Expressions e Declarations d is
56. or equivalently the module import graph must be acyclic if SOURCE imports are ignored Pl The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 55 327 For every module A hs that is SOURCE imported in this way there must exist a source file A hs boot This file contains an abbreviated version of A hs thus module A where newtype TA MkTA Int To compile these three files issue the following commands cl E Alas gon Produces A hi boot A o boot ghe e BAS Consumes A hi boot produces B hi B o GaG e A nS T Consumes B hi produces A hi A o che 9 POG AJO B Mimring Taes oreo Crzam There are several points to note here e The file A hs boot is a programmer written source file It must live in the same directory as its parent source file A hs Currently if you use a literate source file A 1hs you must also use a literate boot file A Lhs boot and vice versa e A hs boot file is compiled by GHC just like a hs file cia e Acs OO When a hs boot file A hs boot is compiled it is checked for scope and type errors When its parent module A hs is compiled the two are compared and an error is reported if the two are inconsistent e Just as compiling A hs produces an interface file A hi and an object file A o so compiling A hs boot produces an interface file A hi boot and an pseudo object file A o boot The pseudo object file A o
57. output of specialisation pass ddump rules dumps all rewrite rules specified in this module see Section 7 23 7 ddump rule firings dumps the names of all rules that fired in this module ddump rule rewrites dumps detailed information about all rules that fired in this module ddump vect dumps the output of the vectoriser ddump simpl simplifier output Core to Core passes ddump inlinings inlining info from the simplifier ddump stranal strictness analyser output ddump strsigs strictness signatures ddump cse CSE pass output ddump worker wrapper worker wrapper split output ddump occur anal occurrence analysis output ddump prep output of core preparation pass ddump stg output of STG to STG passes ddump cmm Print the C code out ddump opt cmm Dump the results of C to C optimising passes ddump asm assembly language from the native code generator ddump 11vm LLVM code from the LLVM code generator ddump bcos byte code compiler output The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 106 327 ddump foreign dump foreign export stubs ddump simpl iterations Show the output of each iteration of the simplifier each run of the simplifier has a maxi mum number of iterations normally 4 This outputs even more information than ddump simpl phases ddump simpl stats Dump statistics about how many of each kind of transformatio
58. plus number both loosely interpreted The letter gives some idea of where the Unique came from e g _ means built in type variable t means from the typechecker s means from the simplifier and so on The number is printed fairly compactly in a base 62 format which everyone hates except me WDP Remember everything has a Unique and it is usually printed out when debugging in some form or another So here we go Desugared MESA aos Salio 8 eoe 54 gt Na as 41 gt 8 4 gt les 4 p MALES is the Ville le ore Melno Sia _4 is the Unique for the type variable template a Num a _4 is a dictionary argument NI_ _NI_ means no pragmatic information yet it will later evolve into the GHC_PRAGMA info that goes into interface files Main skip2 r1L6 IN _4 gt d Num t4Gt gt let feos i areca gS A Ss A gt ol 2NI t4Hg r3JH _4 d Num t4Gt oe MC gg Mnef Ai 4 NI fromint tds fromtnti r3JX 4 d Num t 46 The class method Unique r3JH selects the addition code from a Num dictionary now an explicit lambda d argument The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 108 327 Because Core is 2nd order lambda calculus type applications cial dlemiodas Y cues Solicite So y des music ejpsllalcel stoma type
59. producing a program more quickly Don t use O or especially O2 By using them you are telling GHC that you are willing to suffer longer compilation times for better quality code GHC is surprisingly zippy for normal compilations without O Use more memory Within reason more memory for heap space means less garbage collection for GHC which means less compilation time If you use the Rghc timing option you ll get a garbage collector report Again you can use the cheap and nasty RTS S RTS option to send the GC stats straight to standard error If it says you re using more than 20 of total time in garbage collecting then more memory might help use the H lt size gt option Increasing the default allocation area size used by the compiler s RTS might also help use the RTS A lt size gt RTS option If GHC persists in being a bad memory citizen please report it as a bug Don t use too much memory As soon as GHC plus its fellow citizens other processes on your machine start using more than the real memory on your machine and the machine starts thrashing the party is over Compile times will be worse than terrible Use something like the csh builtin time command to get a report on how many page faults you re getting If you don t know what virtual memory thrashing and page faults are or you don t know the memory configuration of your machine don t try to be clever about memory use you ll
60. rarely used reset hpcdirs empty e Nen listo fhm edancais rarely used SOU EDUCA O UE hpc help draft Usage hipe drat EOP TON Exes PAE Options exclude PACKAGE MODULE exclude MODULE and or PACKAGE include PACKAGE MODULE include MODULE and or PACKAGE srcdir DIR path to source directory of hs files multi use of srcdir possible hpcdir DIR append sub directory that contains mix files default hpc rarely used reset hpcdirs empty the list of hpcdir s rarely used output FILE Eu OULPUL F Ci 5 7 4 Caveats and Shortcomings of Haskell Program Coverage HPC does not attempt to lock the tix file so multiple concurrently running binaries in the same directory will exhibit a race condition There is no way to change the name of the tix file generated apart from renaming the binary HPC does not work with GHCi 5 8 Using ticky ticky profiling for implementors Because ticky ticky profiling requires a certain familiarity with GHC internals we have moved the documentation to the GHC developers wiki Take a look at its overview of the profiling options which includeds a link to the ticky ticky profiling page The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 148 327 Chapter 6 Advice on sooner faster smaller thriftier Please advise us of other helpful hints that should go here 6 1 Sooner
61. test hs 3 6 parse error on input where becomes test296 hs 3 6 10 parse error on input where And multi line spans are possible too test hs 5 4 07 7 Conflicting definitions for Bound at test hs 5 4 resis Ast Gc a tame lomas Ejaguljo Berg Ely 19 El al Note that line numbers start counting at one but column numbers start at zero This choice was made to follow existing convention i e this is how Emacs does it Hsize Set the minimum size of the heap to size This option is equivalent to RTS Hsize see Section 4 17 3 Rghc timing Prints a one line summary of timing statistics for the GHC run This option is equivalent to RTS tstd err see Section 4 17 3 4 7 Filenames and separate compilation This section describes what files GHC expects to find what files it creates where these files are stored and what options affect this behaviour Note that this section is written with hierarchical modules in mind see Section 7 3 6 hierarchical modules are an extension to Haskell 98 which extends the lexical syntax of module names to include a dot Non hierarchical modules are thus a special case in which none of the module names contain dots Pathname conventions vary from system to system In particular the directory separator is on Unix systems and A on Windows systems In the sections that follow we shall consistently use as the directory separator substitute this for the
62. to avoid the need to wait for blocked threads when a standalone executable exits Since the program and all its threads are about to terminate at the same time that the code is removed from memory it isn t necessary to ensure that the threads have exited first Unofficially if you want to use this fast and loose version of hs_exit then call shut downHaskellAndExit instead 8 2 5 Floating point and the FFI The standard C99 fenv h header provides operations for inspecting and modifying the state of the floating point unit In particular the rounding mode used by floating point operations can be changed and the exception flags can be tested In Haskell floating point operations have pure types and the evaluation order is unspecified So strictly speaking since the fenv h functions let you change the results of or observe the effects of floating point operations use of fenv h renders the behaviour of floating point operations anywhere in the program undefined Having said that we can document exactly what GHC does with respect to the floating point state so that if you really need to use fenv h then you can do so with full knowledge of the pitfalls GHC completely ignores the floating point environment the runtime neither modifies nor reads it The floating point environment is not saved over a normal thread context switch So if you modify the floating point state in one thread those changes may be visible in other threads
63. 2 5 1 for more information See also the sprint command which works like print but does not bind new variables quit Quits GHCi You can also quit by typing control D at the prompt reload Attempts to reload the current target set see load if any of the modules in the set or any dependent module has changed Note that this may entail loading new modules or dropping modules which are no longer indirectly required by the target run See main script n filename Executes the lines of a file as a series of GHCi commands This command is compatible with multiline statements as set by set m set option Sets various options See Section 2 8 for a list of available options and Section 4 19 10 for a list of GHCi specific flags The set command by itself shows which options are currently set It also lists the current dynamic flag settings with GHCi specific flags listed separately set args arg Sets the list of arguments which are returned when the program calls System getArgs set editor cmd Sets the command used by edit to cmd set prog prog Sets the string to be returned when the program calls System get ProgName set prompt prompt Sets the string to be used as the prompt in GHCi Inside prompt the sequence s is replaced by the names of the modules currently in scope 1 is replaced by the line number as referenced in compiler messages of the current prompt and is replaced by If prompt starts with
64. 24 8 Eso classe olS 16 SOS OM pass SRA Sis 3 CET NAS 00 8 MES OS ON SADO 9 o SQL 24 10 23 eso lis 3281445 MIS OR Noe OR 2A Sis 1 3 CELT cs SAO Oo MS ES OS C O 3 55 14 CSOLE ANS LR IA1D 24 15 2 csoru Jas 2215 48 CE csore laas ONIS 55 lt end of history gt To examine one of the steps in the history use back sons Moni Elk Logged breakpoint at qsort hs 3 24 38 wesrle Sa le as al el ge a I l CEOLE aas S ZASE AMS gt Note that the local variables at each step in the history have been preserved and can be examined as usual Also note that the prompt has changed to indicate that we re currently examining the first step in the history 1 The command forward can be used to traverse forward in the history The trace command can be used with or without an expression When used without an expression tracing begins from the current breakpoint just like step The history is only available when using trace the reason for this is we found that logging each breakpoint in the history cuts performance by a factor of 2 or more By default GHCi remembers the last 50 steps in the history but this can be changed with the fghci hist size n option The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 30 327 2 5 6 Debugging exceptions Another common question that comes up when debugging is where did this exception come from Exceptions such
65. 252 7 18 2 Conditional commands oe os s s e a ewe e k eE D E E VAE ee 253 7 18 3 Defining your own control structures 2 ee 253 7 18 4 Primitive constructs ge s e eon a a A a e A 254 7 18 5 Differences with the paper 255 T180 Portable dui 2 25 is boat a E a di hee ae See he 2 ee ee e 255 7419 Bang pateras sd A A Ae a 256 7 19 1 Informal description of bang patterns ee 256 7 19 2 Syntaxand semantics 0 66 ck eG RG a RG BO ee 257 T20 ASSertionS pi aun rr A wR A A E 258 72 Statie pointers cid e dd a de a a ds a e SES 258 7 21 1 Using static pointers ee 258 7 21 2 Static semantics of static pointers ee 239 T2 Prao INAS ae e A A ae DA AA AS A A amp Hs 259 71 22 1 LANGUAGE pragiias 4 44 4055 4 BAPE oe ERR EE a e 260 7 22 2 OPTIONS_GHC pragma o e coe de t e e R E E ee 260 7 22 33 INCLUDE pragma so sect aac ne ead k ea p e e e e ae bd E a 260 7 22 4 WARNING and DEPRECATED pragmas aaa 2 2 ee 260 T22 MINIMAL pragma 4 5 4 264 8 dug ee ey Is amp Be Go eee A AA 261 7 22 6 INLINE and NOINLINE pragmas 0 0002 2 ee 261 722 01 INLINE pragma i eoe s m isis a A oe a eee 261 7 22 6 2 INLINABLE pragma ns par Ge beet bee e ee BH be dee ee ees 263 7 22 6 3 NOINLINE pragma soo 6s ce e ee ER Re RR ER EA ee e 263 7 22 64 CONLIKE modifier 2 0 00 0000000022 2 eee 263 7 22 09 Phase contiol icp cb wk a Be O Se a a RE Ae ae we a 263 1224 LINE pragmans os sudores apra da Pad ee be eR ES ee
66. 4 1 Foreign imports and multi threading When you call a foreign imported function that is annotated as safe the default and the program was linked using threadead then the call will run concurrently with other running Haskell threads If the program was linked without threaded then the other Haskell threads will be blocked until the call returns This means that if you need to make a foreign call to a function that takes a long time or blocks indefinitely then you should mark it safe and use threaded Some library functions make such calls internally their documentation should indicate when this is the case If you are making foreign calls from multiple Haskell threads and using threaded make sure that the foreign code you are calling is thread safe In particularly some GUI libraries are not thread safe and require that the caller only invokes GUI methods from a single thread If this is the case you may need to restrict your GUI operations to a single Haskell thread and possibly also use a bound thread see Section 8 2 4 2 Note that foreign calls made by different Haskell threads may execute in parallel even when the RTS N flag is not being used Section 4 15 2 The RTS N flag controls parallel execution of Haskell threads but there may be an arbitrary number of foreign calls in progress at any one time regardless of the RTS N value If a call is annotated as interruptible and the program was multithreaded the call may
67. 66 107 dcore lint option 303 ddump options 105 ddump asm 105 ddump bcos 105 ddump cmm 105 ddump core stats 106 ddump cse 105 ddump deriv 105 ddump ds 105 ddump foreign 106 ddump hi 53 ddump hi diffs 53 ddump hi diffs option 304 ddump if trace 106 ddump inlinings 105 ddump llvm 105 ddump minimal imports 54 ddump occur anal 105 ddump opt cmm 105 ddump parsed 105 ddump prep 105 ddump rn 105 ddump rn trace 106 ddump rule firings 105 ddump rule rewrites 105 ddump rules 105 ddump simpl 105 ddump simpl iterations 106 ddump simpl stats option 106 ddump spec 105 ddump splices 105 ddump stg 105 ddump stranal 105 ddump strsigs 105 ddump tc 105 ddump tc trace 106 ddump tv trace 106 ddump types 105 ddump vect 105 ddump worker wrapper 105 debug 90 dfaststring stats 106 distrust 68 distrust all 68 dno debug output 106 dppr case as let 106 dppr colsNNN 106 dppr debug 106 dppr user length 106 dshow passes 106 dshow rn stats 106 dstg lint 107 dsuppress all 106 dsuppress coercions 107 dsuppress idinfo 107 dsuppress module prefixes 107 dsuppress type applications 107 dsuppress type signatures 107 dsuppress uniques 106 dumpdir 52 dverbose core2core 106 dverbose stg2stg 106 dylib install name 91 dynamic 89 dynload 89 eventlog 90 f 73 f options GHC 79 fPIC 88 fasm 88 fbyte
68. 7 10 2 49 327 4 6 Verbosity options See also the help version numeric version and print 1ibdir modes in Section 4 5 v The v option makes GHC verbose it reports its version number and shows on stderr exactly how it invokes each phase of the compilation system Moreover it passes the v flag to most phases each reports its version number and possibly some other information Please oh please use the v option when reporting bugs Knowing that you ran the right bits in the right order is always the first thing we want to verify vn To provide more control over the compiler s verbosity the v flag takes an optional numeric argument Specifying v on its own is equivalent to v3 and the other levels have the following meanings v0 Disable all non essential messages this is the default v1 Minimal verbosity print one line per compilation this is the default when make or interactive is on v2 Print the name of each compilation phase as it is executed equivalent to dAshow passes v3 The same as v2 except that in addition the full command line if appropriate for each compilation phase is also printed v4 The same as v3 except that the intermediate program representation after each compilation phase is also printed excluding preprocessed and C assembly files fprint explicit foralls fprint explicit kinds These two flags control the way in which GHC dis plays types
69. Compilation System User s Guide Version 7 10 2 41 327 When defining GHCi macros there is some important behavior you should be aware of when names may conflict with built in commands especially regarding tab completion For example consider if you had a macro named time and in the shell typed t 3 what should happen The current algorithm we use for completing commands is 1 First look up an exact match on the name from the defined macros 2 Look for the exact match on the name in the built in command list 3 Do a prefix lookup on the list of built in commands if a built in command matches but a macro is defined with the same name as the built in defined pick the macro 4 Do a prefix lookup on the list of built in commands 5 Do a prefix lookup on the list of defined macros Here are some examples 1 You have a macro time and enter t 3 You get type 3 2 You have a macro type and enter t 3 You get type 3 with your defined macro not the builtin 3 You have a macro time and a macro type and enter t 3 You get type 3 with your defined macro 2 10 Compiling to object code inside GHCi By default GHCi compiles Haskell source code into byte code that is interpreted by the runtime system GHCi can also compile Haskell code to object code to turn on this feature use the fobject code flag either on the command line or with set the option fbyte code restores byte code compilation aga
70. D gt Maybe a gt b This output shows that in the context of the current session ie in the scope of Prelude the first group of items from Data Maybe are not in scope althought they are available in fully qualified form in the GHCi session see Sec tion 2 4 5 whereas the second group of items are in scope via Prelude and are therefore available either unqualified or with a Prelude qualifier cd dir Changes the current working directory to dir A symbol at the beginning of dir will be replaced by the contents of the environment variable HOME See also the show paths command for showing the current working directory NOTE changing directories causes all currently loaded modules to be unloaded This is because the search path is usually expressed using relative directories and changing the search path in the middle of a session is not supported cmd expr Executes expr as a computation of type IO String and then executes the resulting string as a list of GHCi commands Multiple commands are separated by newlines The cmd command is useful with def and set stop The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 34 327 complete type n m string literal This command allows to request command completions from GHCi even when interacting over a pipe instead of a proper terminal and is designed for integrating GHCi s completion with text editors and IDEs When called c
71. En show fn v Operationally in a dictionary passing implementation the constructors Baz1 and Baz2 must store the dictionaries for Eq and Show respectively and extract it on pattern matching 7 4 6 3 Record Constructors GHC allows existentials to be used with records syntax as well For example data Counter a forall self NewCounter SES Ss CUE E a lt Self gt Self Cs lay ds US OA O ER Bsr Here tag is a public field with a well typed selector function tag Counter a gt a The self type is hidden from the outside any attempt to apply _this _inc or _display as functions will raise a compile time error In other words GHC defines a record selector function only for fields whose type does not mention the existentially quantified variables This example used an underscore in the fields for which record selectors will not be defined but that is only programming style GHC ignores them To make use of these hidden fields we need to create some helper functions inc Counter a gt Counter a inc NewCounter x i d t NewCounter CENAS a ox alone a _cChisislleiy cl ua se h Glisjollesy s Cownter E gt 10 display NewCounter _this x _display d d x Now we can define counters with different underlying implementations counterA Counter String counterA NewCounter Co as 0 aleve lar eelle Ora vaa Wall counterB Counter String counterB NewCou
72. Eq jo E jo 88 E jo The Generic and Genericl classes mediate between user defined datatypes and their internal representation as a sum of products class Generic a where Encode the representation of a user datatype type Rep a i x Convert from the datatype to its representation from a gt Rep a The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 274 1327 Convert from the representation to the datatype ise A Repa x gt a class Genericl f where type Repl x gt x col 8S a gt INejoll ae El tol 28 REL E a a Genericl is used for functions that can only be defined over type containers such as map Instances of these classes can be derived by GHC with the XDeriveGeneric Section 7 5 4 and are necessary to be able to define generic instances automatically For example a user defined datatype of trees data UserTr a Node a UserTree a UserTree a L eaf gets the following representation instance Generic UserTr a wher Representation type type Rep UserTr a M1 D DlUserTree M1 C C1_0UserTree M1 S NoSelector Kl R a x M1 S NoSelector Kl R UserTree a x Ml S NoSelector Kl R UserTree a M1 C1 1lUserTree Ul ICON VESES tone funceaoms trom Node x L zy gt MI ii ML ML Kil gt lt 23 ML RL 1 lt MI EL ee yy from Leaf M1 R1 M1 Ul to MT LL BL ME RL se es ML RL Li se ML BL EL Mode
73. Found hole _ with inferred constraints To use the inferred type enable PartialTypeSignatures In the type signature for noCs _ gt String As a single extra constraints wildcard is enough to infer any number of constraints only one is allowed in a type signature and it should come last in the list of constraints Extra constraints wildcards cannot be named 7 15 2 Where can they occur Partial type signatures are allowed for bindings pattern and expression signatures In all other contexts e g type class or type family declarations they are disallowed In the following example a wildcard is used in each of the three possible contexts LANGUAGE ScopedTypeVariables foo OO e gs CG 88 Inferred forall w_ w_ gt w 7 16 Deferring type errors to runtime While developing sometimes it is desirable to allow compilation to succeed even if there are type errors in the code Consider the following case The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 243 327 module Main where el ES Alia a a merma preme US Even though a is ill typed it is not used in the end so if all that we re interested in is main it can be useful to be able to ignore the problems in a For more motivation and details please refer to the HaskellWiki page or the original paper 7 16 1 Enabling deferring of type errors The flag fdefer typ rrors controls whether type
74. GHC s runtime system Do NOT try to invoke any Haskell functions before calling hs_ini t bad things will undoubtedly happen We pass references to argc and argv tohs_init so that it can separate out any arguments for the RTS i e those arguments between RTS RTS After we ve finished invoking our Haskell functions we can call hs_exit which terminates the RTS There can be multiple calls to hs_init but each one should be matched by one and only one call to hs_exit L NOTE when linking the final program it is normally easiest to do the link using GHC although this isn t essential If you do use GHC then don t forget the flag no hs main otherwise GHC will try to link to the Main Haskell module To use RTS flags with hs_init we have to modify the example slightly By default GHC s RTS will only accept safe RTS flags see Section 4 12 6 and the rt sopts link time flag overrides this However rt sopts has no effect when no hs main is in use and the same goes for with rtsopts To set these options we have to call a GHC specific API instead of hs_init include lt stdio h gt include Hs Breed ifdef _ GLASGOW_HASKELL include foo _stub h The outermost hs_exit will actually de initialise the system NOTE that currently GHC s runtime cannot reliably re initialise after this has happened see Section 13 1 1 8 The Glorious Glasgow Haskell Compilation System Us
75. Generalised derived instances for newtypes When you define an abstract type using newt ype you may want the new type to inherit some instances from its representation In Haskell 98 you can inherit instances of Eq Ord Enum and Bounded by deriving them but for any other classes you have to write an explicit instance declaration For example if you define newtype Dollars Dollars Int and you want to use arithmetic on Dollars you have to explicitly define an instance of Num instance Num Dollars where Dollars a Dollars b Dollars atb All the instance does is apply and remove the newt ype constructor It is particularly galling that since the constructor doesn t appear at run time this instance declaration defines a dictionary which is wholly equivalent to the Int dictionary only slower 7 5 5 1 Generalising the deriving clause GHC now permits such instances to be derived instead using the flag XKGeneralizedNewt ypeDeriving so one can write newtype Dollars Dollars Int deriving Eq Show Num and the implementation uses the same Num dictionary for Dollars as for Int Notionally the compiler derives an instance declaration of the form instance Num Int gt Num Dollars which just adds or removes the newt ype constructor according to the type We can also derive instances of constructor classes in a similar way For example suppose we have implemented state and failure monad transformers such that i
76. Haskell Compilation System User s Guide Version 7 10 2 4 327 E Perk 38 CallStack 10 A SI Sia clk will print the occurrence of stk and the call site of The name of the implicit parameter does not matter See the release notes for base for a description of the CallStack type e There is a new extension StaticPointers which allows you to create pointers to expressions which remain valid across pro cesses This is useful for referencing higher order values in distributed systems The pointers are created with a new keyword staticasinx static abc 123 StaticPtr String All processes which dereference x get the same result that is the body of the static form e Added support for binary integer literals e Simplified rules for implicit quantification In previous versions of GHC it was possible to use the gt arrow to quantify over type variables in data and type declarations without a forall quantifier For example data Fun Fun Ord a gt a gt b was identical to data Fun Fun forall a b Ord a gt a gt b while data Fun Fun a gt b caused a not in scope error This implicit quantification is now deprecated and variables in higher rank constructors should be quantified with forall regardless of whether a class context is present or not GHC 7 10 raises a warning controlled by fwarn context quantification enabled by default and GHC 7 12 will raise an error See examples in GHC documentation
77. Here s an example of a command that takes an argument It s a re implementation of cd Prelude gt let mycd d Directory setCurrentDirectory d gt gt return Prelude gt def mycd mycd Prelude gt mycd Or I could define a simple way to invoke ghc make Main in the current directory Prelude gt def make _ gt return ghc make Main We can define a command that reads GHCi input from a file This might be useful for creating a set of bindings that we want to repeatedly load into the GHCi session Prelude gt def readFile Prelude gt cmds ghci Notice that we named the command by analogy with the Unix shell command that does the same thing Typing def on its own lists the currently defined macros Attempting to redefine an existing command name results in an error unless the def form is used in which case the old command with that name is silently overwritten delete num Delete one or more breakpoints by number use show breaks to see the number of each breakpoint The x form deletes all the breakpoints edit file Opens an editor to edit the file file or the most recently loaded module if file is omitted If there were errors during the last loading the cursor will be positioned at the line of the first error The editor to invoke is taken from the EDITOR environment variable or a default editor on your system if EDITOR is not set You can change the editor using set edi
78. LINE pragma LINE pragmas generated from Template Haskell set the file and line position for the duration of the splice and are limited to the splice Note that because Template Haskell splices abstract syntax the file positions are not automatically advanced 7 22 8 RULES pragma The RULES pragma lets you specify rewrite rules It is described in Section 7 23 7 22 9 SPECIALIZE pragma UK spelling also accepted For key overloaded functions you can create extra versions NB more code space specialised to particular types Thus if you have an overloaded function hammeredLookup Ord key gt key value gt key gt valu If it is heavily used on lists with Widget keys you could specialise it as follows SPECIALIZE hammeredLookup Widget value gt Widget gt value e A SPECIALIZE pragma for a function can be put anywhere its type signature could be put Moreover you can also SPECIA LIZE an imported function provided it was given an INLINABLE pragma at its definition site Section 7 22 6 2 e A SPECIALIZE has the effect of generating a a specialised version of the function and b a rewrite rule see Section 7 23 that rewrites a call to the un specialised function into a call to the specialised one Moreover given a SPECIALIZE pragma for a function GHC will automatically create specialisations for any type class overloaded functions called by if they are i
79. RTS behaviour GHC lets you exercise rudimentary control over certain RTS settings for any given program by compiling in a hook that is called by the run time system The RTS contains stub definitions for these hooks but by writing your own version and linking it on the GHC command line you can override the defaults Owing to the vagaries of DLL linking these hooks don t work under Windows when the program is built dynamically You can change the messages printed when the runtime system blows up e g on stack overflow The hooks for these are as follows void OutOfHeapHook unsigned long unsigned long The heap overflow message void StackOverflowHook long int The stack overflow message void MallocFailHook long int The message printed if malloc fails 4 17 2 Miscellaneous RTS options Vsecs Sets the interval that the RTS clock ticks at The runtime uses a single timer signal to count ticks this timer signal is used to control the context switch timer Section 4 14 and the heap profiling timer Section 5 4 1 Also the time profiler uses the RTS timer signal directly to record time profiling samples Normally setting the V option directly is not necessary the resolution of the RTS timer is adjusted automatically if a short interval is requested with the C or i options However setting V is required in order to increase the resolution of the time profiler Using a value of zero disables the RTS clock complet
80. Re compile your program for profiling with the prof option and probably one of the options for adding automatic annotations prof auto is the most common If you are using external packages with cabal you may need to reinstall these packages with profiling support typically this is done with cabal install p package reinstall 2 Having compiled the program for profiling you now need to run it to generate the profile For example a simple time profile can be generated by running the program with RTS p which generates a file named prog prof where prog is the name of your program without the exe extension if you are on Windows There are many different kinds of profile that can be generated selected by different RTS options We will be describing the various kinds of profile throughout the rest of this chapter Some profiles require further processing using additional tools after running the program 3 Examine the generated profiling information use the information to optimise your program and repeat as necessary 5 1 Cost centres and cost centre stacks GHC s profiling system assigns costs to cost centres A cost is simply the time or space memory required to evaluate an expression Cost centres are program annotations around expressions all costs incurred by the annotated expression are assigned to the enclosing cost centre Furthermore GHC will remember the stack of enclosing cost centres for any given expression
81. SO In principle you can use shared without dynamic in the link step That means to statically link the rts all the base libraries into your new shared library This would make a very big but standalone shared library On most platforms however that would require all the static libraries to have been built with fP IC so that the code is suitable to include into a shared library and we do not do that at the moment Warning if your shared library exports a Haskell API then you cannot directly link it into another Haskell program and use that Haskell API You will get linker errors You must instead make it into a package as described in the section above 4 13 4 Finding shared libraries at runtime The primary difficulty with managing shared libraries is arranging things such that programs can find the libraries they need at runtime The details of how this works varies between platforms in particular the three major systems Unix ELF platforms Windows and Mac OS X The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 93 327 4 13 4 1 Unix On Unix there are two mechanisms Shared libraries can be installed into standard locations that the dynamic linker knows about For example usr lib or usr local lib on most systems The other mechanism is to use a runtime path or rpath embedded into programs and libraries themselves These paths can either be absolute paths or on at least Linux and Solaris they can be p
82. Some details e The type signature in the instance declaration must be more polymorphic than or the same as the one in the class declaration instantiated with the instance type For example this is fine instance Eq a gt Eq T a where torecdll 199 19 gt 19 gt Bool Al Here the signature in the instance declaration is more polymorphic than that required by the instantiated class method e The code for the method in the instance declaration is typechecked against the type signature supplied in the instance declara tion as you would expect So if the instance signature is more polymorphic than required the code must be too The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 204 327 e One stylistic reason for wanting to write a type signature is simple documentation Another is that you may want to bring scoped type variables into scope For example class C a where OO ss la gt a gt a Rol instance C a gt C T a where foo forall by og Ta gt 1 a lol HOO x My i we Bes where ze es Mol ll Provided that you also specify XScopedTypeVariables Section 7 13 8 the forall b scopes over the definition of foo and in particular over the type signature for xs 7 6 4 Overloaded string literals GHC supports overloaded string literals Normally a string literal has type String but with overloaded string literals enabled with XOverloadedStrings
83. Storable Prelude gt complete repl map E map mapM map MON Prelude gt complete repl 5 10 map O continue Continue the current evaluation when stopped at a breakpoint ctags filename etags filename Generates a tags file for Vi style editors ctags or Emacs style editors etags If no filename is specified the default tags or TAGS is used respectively Tags for all the functions constructors and types in the currently loaded modules are created All modules must be interpreted for these commands to work def name expr def is used to define new commands or macros in GHCi The command def name expr defines a new GHCi command name implemented by the Haskell expression expr which must have type String gt IO String When name argsis typed at the prompt GHCi will run the expression name args take the resulting String and feed it back into GHCi as a new sequence of commands Separate commands in the result must be separated by An That s all a little confusing so here s a few examples To start with here s a new GHCi command which doesn t take any arguments or produce any results it just outputs the current date amp time The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 35 327 Prelude gt let date _ Time getClockTime gt gt print gt gt return Prelude gt def date date Prelude gt date Fri Mar 23 15 16 40 GMT 2001
84. Term a gt Term o gt Term a b e You can use a deriving clause on a GADT style data type declaration For example these two declarations are equivalent data Maybel a where iMenclnalveil 26 May DSi Justi 28 a gt Weybel a Clereatwaliavej Iie Oed data Maybe2 a Nothing2 Just2 a deriving Eq Ord The type signature may have quantified type variables that do not appear in the result type data Foo where MkFoo 31 a gt le Bool gt Foo Nil roo Here the type variable a does not appear in the result type of either constructor Although it is universally quantified in the type of the constructor such a type variable is often called existential Indeed the above declaration declares precisely the same type as the data Foo in Section 7 4 6 The type may contain a class context too of course data Showable where MkShowable Show a gt a gt Showable e You can use record syntax on a GADT style data type declaration data Person where Adulti name ES Strang a chilladren e l Eers onii gt Person Coide 23 Show a gt I meme 33 Terraine tie 23 E gt Person As usual for every constructor that has a field the type of field must be the same modulo alpha conversion The Child constructor above shows that the signature may have a context existentially quantified variables and strictness annotations just as in the non record case NB the type that follows the double colon
85. The it variable Whenever an expression or a non binding statement to be precise is typed at the prompt GHCi implicitly binds its value to the variable it For example Prelude gt 1 2 3 Prelude gt it 2 6 What actually happens is that GHCi typechecks the expression and if it doesn t have an IO type then it transforms it as follows an expression e turns into let it e prime alc which is then run as an O action Hence the original expression must have a type which is an instance of the Show class or GHCi will complain Prelude gt id lt interactive gt 1 0 No instance for Show a gt a cie SAE Geeta OM ES Cl Mojciiie Ele lt i gt Oz Possible fix add an instance declaration for Show a gt a In the expression print it In a do expression print it The error message contains some clues as to the transformation happening internally If the expression was instead of type IO a for some a then it will be bound to the result of the IO computation which is of type a eg Prelude gt Time getClockTime Wed Mar 14 12 23 13 GMT 2001 Prelude gt print it Wed Mar 14 12 23 13 GMT 2001 The corresponding translation for an IO typed e is Ie lt 8 Note that it is shadowed by the new value each time you evaluate a new expression and the old value of it is lost 2 4 8 Type defaulting in GHCi Consider this GHCi session ghci gt reverse What should GHCi do Strictly speaking
86. The role of a type parameter says what we need to know about the two differing type arguments in order to know that the two outer types have the same representation in the example what must be true about Age and Int in order to show that T Age Bool c has the same representation as T Int Bool c GHC supports three different roles for type parameters nominal representational and phantom If a type parameter has a nominal role then the two types that differ must not actually differ at all they must be identical after type family reduction If a type parameter has a representational role then the two types must have the same representation If T s first parameter s role is representational then T Age Bool candT Int Bool c would have the same representation because Age and Int have the same representation If a type parameter has a phantom role then we need no further information Here are some examples data Simple a MkSimple a a has role representational type family F type instance F Int Bool type instance F Age Char data Complex a MkComplex F a a has role nominal data Phant a MkPhant Bool a has role phantom The type Simple has its parameter at role representational which is generally the most common case Simple Age would have the same representation as Simple Int The type Complex on the other hand has its parameter at role nominal because Simple Age and Simple Int are not the same Lastly Phant Ag
87. The variable y in contrast is left unchanged from the list form introduced by the grouping then group using f The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 167 327 With this form of the group statement f is required to simply have the type forall a a gt a which will be used to group up the comprehension so far directly An example of this form is as follows output x w lt ARES pss Wael ile then group using inits This will yield a list containing every prefix of the word hello written out 5 times pu Mio Moye MS Mc Micllol mella Mcllone nella Winsililkolne til Woe il Ileylaveyik lot 4 45 hellohelloh lt 7 3 15 Monad comprehensions Monad comprehensions generalise the list comprehension notation including parallel comprehensions Section 7 3 13 and trans form comprehensions Section 7 3 14 to work for any monad Monad comprehensions support e Bindings a ES disc lp y lt guste 2 Bindings are translated with the gt gt and return functions to the usual do notation do x lt Just 1 y lt JUST 2 return x y e Guards A E ROSES 5 I Guards are translated with the guard function which requires a MonadP lus instance Glo os lt AO guard x lt 5 return x e Transform statements as with XTransformListComp L Say se lt ES ile akXllp Toen taks 2 This translates to Choy 2 5
88. Version 7 10 2 5 327 e ddump simpl phases and ddump core pipeline flags have been removed e Many more options have learned to respect the ddump to file For example you can use ddump to file with ddump splices to produce a dump splices file for each file that uses Template Haskell This should be much easier to understand on a larger project than having everything being dumped to stdout e Compiler plugins with the fplugin flag may now modify the behaviour of the constraint solver to add new functionality to GHC s typechecker See Section 9 3 4 for more details e A new warning flag fwarn missing exported sigs has been added The behavior is similar to fwarn miss ing signatures but GHC will only flag exported values This flag takes precedence over fwarn missing signat ures so it can be used in conjunction with Wa11 e A new warning flag fwarn unticked promoted constructors has been added This flag causes GHC to warn when you use a promoted constructor without using a tick preceding its name For example data Nat Succ Nat Zero data Vec n s where Nail s Wes ezo a Cons t a Vee a a gt Vec suce m a Will raise two warnings because Zero and Succ are not written as Zero and Succ This warning is enabled by default in Wal1 mode e Added the option dth dec file This dumps out a th hs file of all Template Haskell declarations in a corresponding hs file The idea is that appli
89. Win32 DLL 311 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 324 327 D debugger in GHCi 24 debugging options for GHC 105 defaulting mechanism warning 64 dependencies in Makefiles 58 dependency generation mode 46 depends package specification 77 DEPRECATED 260 deprecated flags 61 deprecations 61 description package specification 76 DLL creation mode 46 DLLs Win32 311 do binding apparently erroneous 66 do binding unused 65 do notation in GHCi 16 dumping GHC intermediates 105 duplicate constraints warning 62 duplicate exports warning 62 dynamic options 39 45 Dynamic libraries using 91 Dynamic link libraries Win32 311 E encoding 50 Environment variable GHC_PACKAGE_PATH 70 environment variable for setting RTS options 97 eval mode 46 eventlog files 102 events 102 export lists duplicates 62 exposed package specification 76 exposed modules package specification 76 extended list comprehensions 165 extensions options controlling 152 extensions GHC 152 extra libraries package specification 77 F faster compiling 148 faster programs how to produce 149 FFI GHCi support 12 fields missing 63 file suffixes for GHC 46 filenames 50 of modules 13 finding interface files 51 floating point exceptions 317 forall 176 forcing GHC phase options 85 foreign 176 foreign export with GHC 290 Foreign Function Interf
90. a ghci file in a directory with a Haskell project is a useful way to set certain project wide options so you don t have to type them every time you start GHCi eg 1f your project uses multi parameter type classes scoped type variables and CPP and has source files in three subdirectories A B and C you might put the following lines in ghci set XMultiParamTypeClasses XScopedTypeVariables cpp SSL WAI RIC Note that strictly speaking the i flag is a static one but in fact it works to set it using set like this The changes won t take effect until the next Load though Once you have a library of GHCi macros you may want to source them from separate files or you may want to source your ghci file into your running GHCi session while debugging it def source readFile With this macro defined in your ghci file you can use source file to read GHCi commands from file You can find and contribute other suggestions for ghci files on this Haskell wiki page GHC GHCi Additionally any files specified with ghci script flags will be read after the standard files allowing the use of custom ghci files Two command line options control whether the startup files files are read ignore dot ghci Don t read either ghci or the other startup files when starting up ghci script Read a specific file after the usual startup files Maybe be specified repeatedly for multiple inputs The Glorious Glasgow Haskell
91. a gt b S 22 a All this behaviour contrasts with Haskell 98 s peculiar treatment of contexts on a data type declaration Section 4 2 1 of the Haskell 98 Report In Haskell 98 the definition data Eq a gt Set a MkSet a gives MkSet the same type as MkSet above But instead of making available an Eq a constraint pattern matching on MkSet requires an Eq a constraint GHC faithfully implements this behaviour odd though it is But for GAD Estyle declarations GHC s behaviour is much more useful as well as much more intuitive The rest of this section gives further details about GADT style data type declarations e The result type of each data constructor must begin with the type constructor being defined If the result type of all constructors has the form T al an where al an are distinct type variables then the data type is ordinary otherwise is a generalised data type Section 7 4 8 e As with other type signatures you can give a single signature for several data constructors In this example we give a single signature for T1 and T2 data T a where Tipe 29 2 gt Toa Se 258 a e The type signature of each constructor is independent and is implicitly universally quantified as usual In particular the type variable s in the data T a where header have no scope and different constructors may have different universally quantified type variables data T a where The a
92. a b where data Ta Only one of the two class parameters is a parameter to the data family Hence the following instance declaration is invalid c d where MET e d instance C data T c WRONG Yoel is mot ain Secos Here the right hand side of the data instance mentions the type variable d that does not occur in its left hand side We cannot admit such data instances as they would compromise type safety 7 7 3 4 Instance contexts and associated type and data instances Associated type and data instance declarations do not inherit any context specified on the enclosing instance For type instance declarations it is unclear what the context would mean For data instance declarations it is unlikely a user would want the context repeated for every data constructor The only place where the context might likely be useful is in a deriving clause of an associated data instance However even here the role of the outer instance context is murky So for clarity we just stick to the rule above the enclosing instance context is ignored If you need to use a non trivial context on a derived instance use a standalone deriving clause at the top level 7 7 4 Import and export The rules for export lists Haskell Report Section 5 2 needs adjustment for type families e The form T where T is a data family names the family T and all the in scope constructors whether in scope qualified or unqualified that are data instances of
93. a binary relation on types or type constructors depending on the kinds of a and b Extra clauses can be included in the definition of classes to add information about dependencies between parameters as in the following examples class Dab a gt b where class Ha o a gt br b gt a where The notation a gt b used here between the and where symbols not to be confused with a function type indicates that the a parameter uniquely determines the b parameter and might be read as a determines b Thus D is not just a relation but actually a partial function Similarly from the two dependencies that are included in the definition of E we can see that E represents a partial one one mapping between types More generally dependencies take the form x1 xn gt yl ym where x1 xn and yl yn are type variables with n gt 0 and m gt 0 meaning that the y parameters are uniquely determined by the x parameters Spaces can be used as separators if more than one variable appears on any single side of a dependency as in t gt a b Note that a class may be annotated with The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 197 327 multiple dependencies using commas as separators as in the definition of E above Some dependencies that we can write in this notation are redundant and will be rejected because they don t serve any useful purpose and may instead indicate an error
94. a day to day basis and we don t have finer granularity in the values of _ GLASGOW_HASKELL___ you should only conditionally compile using predicates which test whether __GLASGOW_HASKELL___is equal to later than or earlier than a given major release Unstable snapshots We may make snapshot releases of the HEAD available for download and the latest sources are available from the git repositories Unstable snapshot releases are named x y YYYYMMDD where YYYYMMDD is the date of the sources from which the snap shot was built For example 6 7 20040225 would be a snapshot of the HEAD before the creation of the 6 8 branch The value of __GLASGOW_HASKELL__ for a snapshot release is the integer xyy You should never write any conditional code which tests for this value however since interfaces change on a day to day basis and we don t have finer granularity in the values of _ GLASGOW_HASKELL___ you should only conditionally compile using predicates which test whether ___GLASGOW_HASKELL___is equal to later than or earlier than a given major release The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 3 327 The version number of your copy of GHC can be found by invoking ghc with the version flag see Section 4 6 1 5 Release notes for version 7 10 1 The significant changes to the various parts of the compiler are listed in the following sections There have also been numerous bug fixes and
95. all of then can be the class parameters Each class parameter may only be used at most once per associated type but some may be omitted and they may be in an order other than in the class head Hence the following contrived example is admissible class C a b c where Eype T a x 3g e Here c and a are class parameters but the type is also indexed on a third parameter x 7 7 3 1 Associated instances When an associated data or type synonym family instance is declared within a type class instance we optionally may drop the instance keyword in the family instance instance GMapKey a GMapKey b gt GMapKey Either a b where data GMap Either a b v GMapEither GMap a v GMap b v instance Eq Elem gt Collects e wher type Elem e e The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 213 327 Note the following points e The type indexes corresponding to class parameters must have precisely the same shape the type given in the instance head To have the same shape means that the two types are identical modulo renaming of type variables For example instance Eq Elem e gt Collects e where Choose one of the following alternatives type Elem e ES type Elem x x Ol type Elem x x BAD shape of x is different to e type Elem Maybe x x BAD shape of Maybe x is different to e
96. also the NOINLINE Section 7 22 6 3 and INLINABLE Section 7 22 6 2 pragmas 7 22 6 2 INLINABLE pragma An INLINABLE f pragma on a function f has the following behaviour e While INLINE says please inline me the INLINABLE says feel free to inline me use your discretion In other words the choice is left to GHC which uses the same rules as for pragma free functions Unlike INLINE that decision is made at the call site and will therefore be affected by the inlining threshold optimisation level etc e Like INLINE the INLINABLE pragma retains a copy of the original RHS for inlining purposes and persists it in the interface file regardless of the size of the RHS e One way to use INLINABLE is in conjunction with the special function inline Section 7 24 The call inline f tries very hard to inline To make sure that can be inlined it is a good idea to mark the definition of as INLINABLE so that GHC guarantees to expose an unfolding regardless of how big it is Moreover by annotating f as INLINABLE you ensure that s original RHS is inlined rather than whatever random optimised version of GHC s optimiser has produced e The INLINABLE pragma also works with SPECIALISE if you mark function f as INLINABLE then you can subsequently SPECIALISE in another module see Section 7 22 9 e Unlike INLINE it is OK to use an INLINABLE pragma on a recursi
97. an instance head e Type synonym families may not appear at all in an instance head The reason for the latter restriction is that there is no way to check for instance matching Consider type family F a type instance F Bool Int class Ca instance C Int instance C F a Now a constraint C F Bool would match both instances The situation is especially bad because the type instance for F Bool might be in another module or even in a module that is not yet written However type class instances of instances of data families can be defined much like any other data type For example we can say dato in Sonico rmt ri tme T2 BOOL instance Eq T Int where T1 i T1 j i j T2 i 12 j i False Note that class instances are always for particular instances of a data family and never for an entire family as a whole This is for essentially the same reasons that we cannot define a toplevel function that performs pattern matching on the data constructors of different instances of a single type family It would require a form of extensible case construct Data instance declarations can also have deriving clauses For example we can write data GMap v GMapUnit Maybe v deriving Show which implicitly defines an instance of the form instance Show v gt Show GMap v where 7 8 Kind polymorphism This section describes kind polymorphism and extension enabled by XPolyKinds It is described
98. appropriate character for your system 4 7 1 Haskell source files Each Haskell source module should be placed in a file on its own Usually the file should be named after the module name replacing dots in the module name by directory separators For example on a Unix system the module A B C should be placed in the file A B C hs relative to some base directory If the module is not going to be imported by another module Main for example then you are free to use any filename for it GHC assumes that source files are ASCII or UTF 8 only other encodings are not recognised However invalid UTF 8 sequences will be ignored in comments so it is possible to use other encodings such as Latin 1 as long as the non comment source code is ASCII only 4 7 2 Output files When asked to compile a source file GHC normally generates two files an object file and an interface file The object file which normally ends in a o suffix contains the compiled code for the module The interface file which normally ends in a hi suffix contains the information that GHC needs in order to compile further modules that depend on this module It contains things like the types of exported functions definitions of data types and so on It is stored in a binary format so don t try to read one use the show iface option instead see Section 4 7 7 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 51 327 You should t
99. arguments to the pre processor can be passed in using the opt F option These are fed to cmd on the command line after the three standard input and output arguments An example of a pre processor is to convert your source files to the input encoding that GHC expects i e create a script convert sh containing the lines bin sh MSN E YW SBN seat e skeCianye E iki e 0Cr g S2 gt 63 and pass F pgmF convert sh to GHC The f 11 option tells iconv to convert your Latin 1 file supplied in argument 2 while the t utf 8 options tell iconv to return a UTF 8 encoded file The result is redirected into argument 3 The echo LINE 1 2 just makes sure that your error positions are reported as in the original source file The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 88 327 4 12 5 Options affecting code generation fasm Use GHC s native code generatorrather than compiling via LLVM fasm is the default fllvm Compile via LLVMinstead of using the native code generator This will generally take slightly longer than the native code generator to compile Produced code is generally the same speed or faster than the other two code generators Compiling via LLVM requires LLVM to be on the path fno code Omit code generation and all later phases altogether This is useful if you re only interested in type checking code fwrite interface Always write interface files
100. as those raised by error or head have no context information attached to them Finding which particular call to head in your program resulted in the error can be a painstaking process usually involving Debug Trace trace or compiling with profiling and using Debug Trace traceStack or RTS xc see Section 5 3 The GHCi debugger offers a way to hopefully shed some light on these errors quickly and without modifying or recompiling the source code One way would be to set a breakpoint on the location in the source code that throws the exception and then use trace and history to establish the context However head is in a library and we can t set a breakpoint on it directly For this reason GHCi provides the flags fbreak on exception which causes the evaluator to stop when an exception is thrown and fbreak on error which works similarly but stops only on uncaught exceptions When stopping at an exception GHCi will act just as it does when a breakpoint is hit with the deviation that it will not show you any source code location Due to this these commands are only really useful in conjunction with trace in order to log the steps leading up to the exception For example Main gt set fbreak on exception Main gt trace qsort abc undefined Stopped at lt exception thrown gt _exception e lt exception thrown gt Main gt hist l CROPE AMES Zame SES O SSI 5S 5 ESOS 10 3755 A Ore glass R85 o
101. at runtime 92 ALGA lcera e A Aa da 93 4 134 2 MacOSX cer o OO a e a ee a EA 93 Using Concurrent Haskell sgos rss rra a Baek ee RG BO ee 93 Using SMP paralle lism ser 4 1 53 5 20540 4uF PS e Se ee Ee oe eee e bed 94 4 15 1 Compile time options for SMP parallelism 2 0 0000000000 0000 94 4 15 2 RTS options for SMP parallelism 0 0 00 0 00000000000 000 94 4 15 3 Hints for using SMP parallelism 0200000000000 00000000 95 Platform speciiic Flags sip 66 2468 eee Gedo Eo ee Reade woes Cede BESS heeds es 95 Running a compiled program 2 ee 96 4 17 1 Setting RTS options osc ecet raakt aa 0 000000002002 2 2 E E ee 96 4 17 1 1 Setting RTS options on the commandline oaa 96 4 17 1 2 Setting RTS options at compile time e 96 4 17 1 3 Setting RTS options with the GHCRTS environment variable 97 4 17 1 4 Hooks to change RTS behaviour 20 02 20 00000 00004 97 4 17 2 Miscellaneous RTS Options 97 4 17 3 RTS options to control the garbage collector 2 2 ee 98 4 17 4 RTS options for concurrency and parallelism ooo a 102 4 17 5 RTS options for profiling a 102 417 6 TACIS dogo o E a a EE A A BA a a Re ee E 102 4 17 7 RTS options for hackers debuggers and over interested souls o o 103 4 17 8 Getting information about the RTS a 104 Debugging the compiler lt s sec ee 105 4 18 1 Dumpin
102. be empty applied to the appropriate integer value You can have multiple enum definitions with the same t ype this construct does not emit the type definition itself 11 2 3 Custom constructs const type peek poke and ptr are not hardwired into the hsc2hs but are defined in a C template that is included in the C program template hsc h Custom constructs and templates can be used too Any construct with unknown key is expected to be handled by a C template A C template should define a macro or function with name prefixed by hsc_ that handles the construct by emitting the expansion to stdout See template hsc h for examples Such macros can also be defined directly in the source They are useful for making a 1et like macro whose expansion uses other let macros Plain 1et prepends hsc_ to the macro name and wraps the definition in a printf call 11 2 4 Cross compilation hsc2hs normally operates by creating compiling and running a C program That approach doesn t work when cross compiling in this case the C compiler s generates code for the target machine not the host machine For this situation there s a special mode hsc2hs cross compile which can generate the hs by extracting information from compilations only specifically whether or not compilation fails Only a subset of hsc syntax is supported by cross compile The following are unsupported e const_str e
103. be interrupted in the event that the Haskell thread receives an exception The mechanism by which the interrupt occurs is platform dependent but is intended to cause blocking system calls to return immediately with an interrupted error code The underlying operating system thread is not to be destroyed See Section 8 1 4 for more details 8 2 4 2 The relationship between Haskell threads and OS threads Normally there is no fixed relationship between Haskell threads and OS threads This means that when you make a foreign call that call may take place in an unspecified OS thread Furthermore there is no guarantee that multiple calls made by one Haskell thread will be made by the same OS thread This usually isn t a problem and it allows the GHC runtime system to make efficient use of OS thread resources However there are cases where it is useful to have more control over which OS thread is used for example when calling foreign code that makes use of thread local state For cases like this we provide bound threads which are Haskell threads tied to a particular OS thread For information on bound threads see the documentation for the Control Concurrent module 8 2 4 3 Foreign exports and multi threading When the program is linked with threaded then you may invoke foreign exported functions from multiple OS threads concurrently The runtime system must be initialised as usual by calling hs_init and this call must complete before invoking a
104. because the type of empty doesn t mention a Functional dependencies can make the type variable reachable class Coll s a s gt a where empty 8 NS CAS cl gt Gi Alternatively Co11 might be rewritten The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 195 327 class Coll s a where Smery 107503 ise BS Sa gt Gl gt S el which makes the connection between the type of a collection of a s namely s a and the element type a Occasionally this really doesn t work in which case you can split the class like this class CollE s where SMILEYS class CollE s gt Coll s a where SS AS ES 7 6 2 2 Background on functional dependencies The following description of the motivation and use of functional dependencies is taken from the Hugs user manual reproduced here with minor changes by kind permission of Mark Jones Consider the following class intended as part of a library for collection types class Collects ce wher EME 37 Ce insertie gt 8 oe member gt gt Bool The type variable e used here represents the element type while ce is the type of the container itself Within this framework we might want to define instances of this class for lists or characteristic functions both of which can be used to represent collections of any equality type bit sets which can be used to represent collections of characters or hash tables which can be used to repr
105. bie eh eee we Geer OE e Sip ee BG ee ee ee Be Aes Ghd SS A 215 7 7 5 Type families and instance declarations ee 216 7 8 Kind polymorphism 2 2 0 0 nedo de e k k eE 216 7 8 1 Overview of kind polymorphism 2 2 ee 216 TBD OVERVIEW 1 a 4S eos es E ee ee Bee es E De Ae e e 217 7 8 3 Polymorphic kind recursion and complete kind signatures ooa o 217 7 8 4 Kind inference in closed type families e 218 7 8 5 Kind inference in class instance declarations e 219 TO D t typeproMoton s lt iis sp 66 eee a a a e BSS Boo ee es 8 219 FIT Motivation os 64 6 ohne a4 Rec A EA E E A E Y 219 LIZ OVEIVIENW 2 e foc aes a ea E a a ee RRA a Ee eG ee Sea ee 220 7 9 3 Distinguishing between types and constructors 2 2 0 00 eee ee 221 7 9 4 Promoted list and tuple types ee 221 7 9 5 Promoting existential data constructors ooa ee 221 7 9 6 Promoting type operators ooo ee 222 7 10 Type Level Literals succi a ee ae baa BG a ee ee ew U i oe 222 7 10 1 Runtime Values for Type Level Literals o o ee 222 7 10 2 Computing With Type Level Naturals ee 223 7 11 Equality constraints lt oos e eesse eere eretier Ent eeu Eeki heen E ee 223 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 xiii TAL The Coercible consiraint pe 25 pa eae eek a eae PA Pe eR a e 224 712 TheConstraint kind e
106. bindings command Prelude gt show bindings Re 88 lige Prelude gt HINT if you turn on the t option GHCi will show the type of each variable bound by a statement For example Prelude gt set t Prelude gt let x xs 1 x 2 Integer xs Integer 2 4 3 Multiline input Apart from the syntax for multi line input mentioned above GHCi also has a multiline mode enabled by set m in which GHCi detects automatically when the current statement is unfinished and allows further lines to be added A multi line input is terminated with an empty line For example Prelude gt set m Prelude gt let x 42 Prelude The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 18 327 Further bindings can be added to this 1et statement so GHCi indicates that the next line continues the previous one by changing the prompt Note that layout is in effect so to add more bindings to this 1et we have to line them up Prelude gt set m Prelude gt let x 42 Prelude ES Prelude Prelude gt Explicit braces and semicolons can be used instead of layout as usual Prelude gt do Prelude putStrLn hello Prelude putStrLn world Prelude hello world Prelude gt Note that after the closing brace GHCi knows that the current statement is finished so no empty line is required Multiline mode is useful when entering monadic do statements Control Monad State gt flip eva
107. c and hc files __GLASGOW_HASKELL PATCHLEVEL1__ __GLASGOW_HASKELL PATCHLEVEL2__ These macros are available start ing with GHC 7 10 1 For three part GHC version numbers x y z the value of__ GLASGOW_HASKELL_PATCHLEVEL1__ is the integer z For four part GHC version numbers x y z z the value of__GLASGOW_HASKELL_PATCHLEVEL1__ is the integer z while the value of __GLASGOW_HASKELL_PATCHLEVEL2__ is set to the integer z These macros are provided for allowing finer granularity than is provided by __GLASGOW_HASKELL__ Usually this should not be necessary as it s expected for most APIs to remain stable between patchlevel releases but occasionally internal API changes are necessary to fix bugs Also conditional compilation on the patchlevel can be useful for working around bugs in older releases NB These macros are set when pre processing both Haskell source and C source including the C source generated from a Haskell module i e hs 1hs c and hc files MIN_VERSION_GLASGOW_HASKELL x y z z This macro is available starting with GHC 7 10 1 This macro is provided for convenience to write CPP conditionals testing whether the GHC version used is version x y z z or later If compatibility with Haskell compilers including GHC prior to version 7 10 1 which do not define MIN_VERSION_G LASGOW_HASKELL is required the presence of the MIN_VERSION_GLASGOW_HASKELL macro needs to
108. change is that it means IO a actions default to IO which in turn means that ghci won t try to print a result when running them This is particularly important for printf which has an instance that returns IO a However it is only able to return undefined the reason for the instance having this type is so that printf doesn t require extensions to the class system so 1f the type defaults to Integer then ghci gives an error when running a printf See also Section 2 4 1 for how the monad of a computational expression defaults to IO if possible 2 4 9 Using a custom interactive printing function New in version 7 6 1 By default GHCi prints the result of expressions typed at the prompt using the function System IO print Its type signature is Show a gt a gt IO and it works by converting the value to String using show This is not ideal in certain cases like when the output is long or contains strings with non ascii characters The interactive print flag allows to specify any function of type C a gt a gt IO for some constraint C as the function for printing evaluated expressions The function can reside in any loaded module or any registered package As an example suppose we have following special printing module module SpecPrinter wher import System IO sprint a putStrLn show a The sprint function adds an exclamation mark at the end of any printed value Running GHCi with the command ghc
109. class Monad m Monad t m gt Transform t m where lare 38 m a gt ME m a As in Haskell 98 The class hierarchy must be acyclic However the definition of acyclic involves only the superclass relation ships For example this is OK class C a where go 86 D b gt a gt b gt b class C a gt D a where Here C is a superclass of D but it s OK for a class operation op of C to mention D It would not be OK for D to be a superclass of C With the extension that adds a kind of constraints you can write more exotic superclass definitions The superclass cycle check is even more liberal in these case For example this is OK class A cls c where meda 28 Gills gt e gt a class A B c gt B c where A superclass context for a class C is allowed if after expanding type synonyms to their right hand sides and uses of classes other than C to their superclasses C does not occur syntactically in the context 7 6 1 3 Class method types Haskell 98 prohibits class method types to mention constraints on the class type variable thus class Seq s a where frombist aj gt s a elem 23 me a gt gt s a gt BOOL The type of elem is illegal in Haskell 98 because it contains the constraint Eq a constrains only the class type variable in this case a GHC lifts this restriction flag XConstrainedClassMethods 7 6 1 4 Default method signatures Haskell 98 allows you to define a default i
110. closed free variable namely Similarly h is closed even though it is not bound at top level because its only free variable f is closed But k is not closed because it mentions x which is not closed because it is not let bound Notice that a top level binding that is affected by the monomorphism restriction is not closed and hence may in turn prevent generalisation of bindings that mention it The rationale for this more conservative strategy is given in the papers Let should not be generalised and Modular type inference with local assumptions and a related blog post The flag XMonoLocalBinds is implied by XTypeFamilies and XGADTs You can switch it off again with XNoMon oLocalBinds but type inference becomes less predicatable if you do so Read the papers 7 14 Typed Holes Typed holes are a feature of GHC that allows special placeholders written with a leading underscore e g _ _foo _bar to be used as expressions During compilation these holes will generate an error message that describes which type is expected at the hole s location information about the origin of any free type variables and a list of local bindings that might help fill the hole with actual code Typed holes are always enabled in GHC The goal of typed holes is to help with writing Haskell code rather than to change the type system Typed holes can be used to obtain extra information from the type checker which might otherwise be hard to get No
111. combine tix FUNCTION A use the union of th DD E gt lt TIX_FILE gt and or PACKAG and or PACKAG leal eal default ADD files with join function DIFF SUB module namespac default is lt lt hpc map inverts or zeros a t ix file hpc map does not change the original t ix file it generates a new tix file S hpc help map Usage hpc map OPTION Map a function over a single Options IA En alos ale The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 147 327 exclude PACKAGE MODULE exclude MODULE and or PACKAGE include PACKAGE MODULE include MODULE and or PACKAGE m OUPS ILL OUP US g ei function FUNCTION apply function to tix files default ID FUNCTION ID INV ZERO lt union use the union of the module namespace default is lt gt intersection 5 7 3 6 hpc overlay and hpc draft Overlays are an experimental feature of HPC a textual description of coverage hpc draft is used to generate a draft overlay from a tix file and hpc overlay generates a tix files from an overlay o hpc help overlay Usage hpc overlay OPTION lt OVERLAY_FILE gt lt OVERLAY_FILE gt Options srcdir DIR path to source directory of hs files multi use of srcdir possible hpcdir DIR append sub directory that contains mix files default hpc
112. compilation options So before you report a bug because of a core dump you should probably IO scrub your object files make my_prog re make your program use ddump hi diff s to highlight changes as mentioned above us dcore lint to be more paranoid o MIES osa Gf TSE o oo Of course if you have foreign calls in your program then all bets are off because you can trash the heap the stack or whatever My program entered an absent argument This is definitely caused by a bug in GHC Please report it see Section 1 3 What s with this arithmetic or floating exception Int Float and Double arithmetic is unchecked Overflows underflows and loss of precision are either silent or reported as an exception by the operating system depending on the platform Divide by zero may cause an untrapped exception please report it if it does The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 305 327 Chapter 11 Other Haskell utility programs This section describes other program s which we distribute that help with the Great Haskell Programming Task 11 1 Yacc for Haskell happy Andy Gill and Simon Marlow have written a parser generator for Haskell called happy Happy is to Haskell what Yace is to C You can get happy from the Happy Homepage Happy is at its shining best when compiled by GHC 11 2 Writing Haskell interfaces to C code hsc2hs The hs
113. currently live How long this garbage collection took CPU time and elapsed wall clock time How long the program has been running CPU time and elapsed wall clock time How many page faults occurred this garbage collection How many page faults occurred since the end of the last garbage collection Which generation is being garbage collected 4 17 4 RTS options for concurrency and parallelism The RTS options related to concurrency are described in Section 4 14 and those for parallelism in Section 4 15 2 4 17 5 RTS options for profiling Most profiling runtime options are only available when you compile your program for profiling see Section 5 2 and Section 5 4 1 for the runtime options However there is one profiling option that is available for ordinary non profiled executables hT can be shortened to h Generates a basic heap profile in the file prog hp To produce the heap profile graph use hp2ps see Section 5 5 The basic heap profile is broken down by data constructor with other types of closures functions thunks etc grouped into broad categories e g FUN THUNK To get a more detailed profile use the full profiling support Chapter 5 4 17 6 Tracing When the program is linked with the event log option Section 4 12 6 runtime events can be logged in two ways e In binary format to a file for later analysis by a variety of tools One such tool is ThreadScope which interprets the event log to prod
114. database file on top of the current stack Packages in additional databases read this way will override those in the initial stack and those in previously specified databases no global package db Remove the global package database from the package database stack no user package db Prevent loading of the user s local package database in the initial stack clear package db Reset the current package database stack This option removes every previously specified package database including those read from the GHC_PACKAGE_PATH environment variable from the package database stack global package db Add the global package database on top of the current stack This option can be used after no global package db to specify the position in the stack where the global package database should be loaded user package db Add the user s package database on top of the current stack This option can be used after no user package db to specify the position in the stack where the user s package database should be loaded 4 9 5 1 The GHC_PACKAGE PATH environment variable The GHC_PACKAGE_PATH environment variable may be set to a separated separated on Windows list of files containing package databases This list of package databases is used by GHC and ghc pkg with earlier databases in the list overriding later ones This order was chosen to match the behaviour of the PATH environment variable think of it as a list of package databases
115. default Enables the sinking pass in the code generator This optimisation attempts to find identical Cmm blocks and eliminate the duplicates attempts to move variable bindings closer to their usage sites It also inlines simple expressions like literals or registers fcpr off Switch off CPR analysis in the demand analyser fcse On by default Enables the common sub expression elimination optimisation Switching this off can be useful if you have some unsafePerforml0 expressions that you don t want commoned up fdicts cheap A very experimental flag that makes dictionary valued expressions seem cheap to the optimiser fdicts strict Make dictionaries strict fdmd tx dict sel On by default for 00 0 02 Use a special demand transformer for dictionary selectors fdo eta reduction On by default Eta reduce lambda expressions if doing so gets rid of a whole group of lambdas fdo lambda eta expansion On by default Eta expand let bindings to increase their arity feager blackholing Usually GHC black holes a thunk only when it switches threads This flag makes it do so as soon as the thunk is entered See Haskell on a shared memory multiprocessor The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 80 327 fexcess precision 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 t
116. dreaded Monomorphism Restriction o oo 237 7 13 9 2 Generalised typing of mutually recursive bindings o 297 7 13 9 3 Let generalisation o sess ee 237 T14 Typed Holes s 2 2056 dr rra Bw e BES a a BPS a 238 TAS Partial Type Signatures ss ake a E BA A E EA e 239 VAD SYA oe dee Oe Ga a ee eee a ee Ra ee Ee eG ee Sea ee 240 TAS AA Type Wildcards iii wk a Re O a a RA ea ew a 240 7 15 1 2 Named Wildcards mopedi se ba ee eb ees ee Re ewe eR EE a 241 7 15 1 3 Extra Constraints Wildcard ee 241 7 15 2 Where can they Occur eo 6 eR eR ee ae A ee Ee we 242 7 16 Deferring type errors to runtime 2 0 0 000 242 7 16 1 Enabling deferring of type errors 243 7 16 2 Deferred type errorsinGHCi 0 tan tesa peered ee 243 7 17 Template Haskell s c 2 ma 2406 40 2 bGA OES EAE EAR Eee baa ee eA A eS 244 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 xiv TLIRE SYMaX ecer emake A RR A eR a e amp 244 717 2 Using Template Haskell 2045425540040 A A A a 246 7 17 3 Viewing Template Haskell generated code o 247 7 17 4 A Template Haskell Worked Example 20000002002 247 7 17 5 Using Template Haskell with Profiling o e e 248 7 17 6 Template Haskell Quasi quotation 0 000 0022 eee ee 248 TAS Amow notation cours a eS EA Ea RA ee A a ee 250 7 18 1 do notation for commands oaa ee
117. during the run of the program note that the total memory allocation figure isn t the same as the amount of live memory needed by the program at any one time the latter can be determined using heap profiling which we will describe later in Section 5 4 The second part of the file is a break down by cost centre of the most costly functions in the program In this case there was only one significant function in the program namely fib and it was responsible for 100 of both the time and allocation costs of the program The third and final section of the file gives a profile break down by cost centre stack This is roughly a call tree profile of the program In the example above it is clear that the costly call to fib came from main The time and allocation incurred by a given part of the program is displayed in two ways individual which are the costs incurred by the code covered by this cost centre stack alone and inherited which includes the costs incurred by all the children of this node The usefulness of cost centre stacks is better demonstrated by modifying the example slightly main Eo al IN SO ap oj 0 where ic m Spe aLie callo m cul a ely 2 n lt 2 then 1 else fib m i morg Aina Compile and run this program as before and take a look at the new profiling results COST CENTRE MODULE MAIN MAIN CAF GHC IO Handle FD CAF GHC TOP Encoding Leon CAF GHe Conc mcrgnaal
118. e A definition of trust or safety and how it operates along with ways of defining and changing the trust of modules and packages Safe Haskell however does not offer compilation safety During compilation time it is possible for arbitrary processes to be launched using for example the custom pre processor flag This can be manipulated to either compromise a users system at compilation time or to modify the source code just before compilation to try to alter set Safe Haskell flags This is discussed further in section Section 7 29 7 7 29 1 Uses of Safe Haskell Safe Haskell has been designed with two use cases in mind e Enforcing strict type safety at compile time e Compiling and executing untrusted code 7 29 1 1 Strict type safety good style Haskell offers a powerful type system and separation of pure and effectual functions through the IO monad There are several loop holes in the type system though the most obvious offender being the unsafePerformIO IO a gt a function The safe language dialect of Safe Haskell disallows the use of such functions This can be useful for a variety of purposes as it makes Haskell code easier to analyse and reason about It also codifies an existing culture in the Haskell community of trying to avoid using such unsafe functions unless absolutely necessary As such using the safe language through the XSafe flag can be thought of as a way of enforcing good style similar to the function of Wal 1
119. ee 64 ee BOA Sh eee Ree eA baw eee se eo 224 7 13 Other type system extensions o oo 2295 7 13 1 Explicit universal quantification forall 2 e 225 7 13 2 The context of a type Signature 225 7 13 3 Ambiguous types and the ambiguity check o ee 2293 7 13 4 Implicit parameters 227 7 13 4 1 Implicit parameter type constraints e 22 7 13 4 2 Implicit parameter bindings 0 0 000000 000000000000 228 7 13 4 3 Implicit parameters and polymorphic recursion 2 000000000 229 7 13 4 4 Implicit parameters and monomorphism 00000 00000 28 229 7 13 4 5 Special implicit parameters 2 2 0 a 229 7 13 5 Explicitly kinded quantification 02 ee 230 7 13 6 Arbitrary rank polymorphism 2 2 2 ee 231 7 13 6 1 Examples x ss sa a hd ae OR ER ad be ee hea a ee a ee 231 T 13 6 2 Type inference pos se kk ea a a e A BRAGS a a A ee 233 7 13 6 3 Implicit quantification 2 ee 233 7 13 7 Impredicative polymorphism 2 2 ee 234 7 13 8 Lexically scoped type variables 2 2 2 ee 234 TAB BL OVERVIEW kee aw ee Ewa eee bbe Rea be Oe ee E 234 7 13 8 2 Declaration type signatures 2 ee 233 7 13 8 3 Expression type signatures e 235 7 13 8 4 Pattern type Signatures 236 7 13 8 5 Class and instance declarations e 230 7 13 9 Bindings and generalisation ee 23d 7 13 9 1 Switching off the
120. eval no type refinement happens and lots of obscure error messages will occur However the refinement is quite general For example if we had evo NEk Nem A gt a gt A eva MR ME ES The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 187 327 the pattern match causes the type a to be refined to Int because of the type of the constructor Lit and that refinement also applies to the type of j and the result type of the case expression Hence the addition i j is legal These and many other examples are given in papers by Hongwei Xi and Tim Sheard There is a longer introduction on the wiki and Ralf Hinze s Fun with phantom types also has a number of examples Note that papers may use different notation to that implemented in GHC The rest of this section outlines the extensions to GHC that support GADTs The extension is enabled with XGADTs The XGADTs flag also sets XGADTSyntax and XMonoLocalBinds A GADT can only be declared using GADT style syntax Section 7 4 7 the old Haskell 98 syntax for data declarations always declares an ordinary data type The result type of each constructor must begin with the type constructor being defined but for a GADT the arguments to the type constructor can be arbitrary monotypes For example in the Term data type above the type of each constructor must end with Term ty but the ty need not be a type variable e g the Lit constructor It is permitted t
121. evaluate the addends from left to right Note that we use pseq rather than seq The two are almost equivalent but differ in their runtime behaviour in a subtle way seq can evaluate its arguments in either order but pseq is required to evaluate its first argument before its second which makes 1t more suitable for controlling the evaluation order in conjunction with par The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 280 327 When using par the general rule of thumb is that the sparked computation should be required at a later time but not too soon Also the sparked computation should not be too small otherwise the cost of forking it in parallel will be too large relative to the amount of parallelism gained Getting these factors right is tricky in practice It is possible to glean a little information about how well par is working from the runtime statistics see Section 4 17 3 More sophisticated combinators for expressing parallelism are available from the Control Parallel Strategies mod ule in the parallel package This module builds functionality around par expressing more elaborate patterns of parallel compu tation such as parallel map 7 28 5 Data Parallel Haskell GHC includes experimental support for Data Parallel Haskell DPH This code is highly unstable and is only provided as a technology preview More information can be found on the corresponding DPH wiki page 7 29 Safe Haskell S
122. explicit type instance declaration is given for the associated type the default declaration is used instead just as with default class methods Note the following points e The instance keyword is optional There can be at most one default declaration for an associated type synonym A default declaration is not permitted for an associated data type e The default declaration must mention only type variables on the left hand side and the right hand side must mention only type varaibels bound on the left hand side However unlike the associated type family declaration itself the type variables of the default instance are independent of those of the parent class The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 214 327 Here are some examples class C a where type Fl a type instance Fl a a OK type instance Fl a a gt a BAD only one default instance is allowed type F2 ba OK note the family has more type variables than the class type instance F2 c d c gt d OK you don t have to use a in the type instance type F3 a type F3 b b BAD only type variables allowed on the LHS type F4 a type F4 b a BAD YE LCs IgGIE slim S COPE sum ARES 7 7 3 3 Scoping of class parameters The visibility of class parameters in the right hand side of associated family instances depends solely on the parameters of the family As an example consider the simple class declaration class C
123. extra constraints wildcard indicates that an arbitrary number of extra constraints may be inferred during type checking and will be added to the type signature In the example below the extra constraints wildcard is used to infer three extra constraints The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 242 327 sudot OS 28 gt El gt Sicsealinwe arbitCs show suce x show x x Inferred E corall as aula e Mer Ely Sino E gt a gt Suc EN ON SST ASS Found hole _ with inferred constraints Enum a Eq a Show a To use the inferred type enable PartialTypeSignatures In the type signature for arbitCs _ gt a gt String An extra constraints wildcard shouldn t prevent the programmer from already listing the constraints he knows or wants to anno tate e g Also a correct partial type signature adoos 28 mauia Ej gt 6 gt Sene codo cos e euglosliciGs Y Inferred F forall a Enum a Show a Eq a gt a gt String ERRO TE St lis eS Found hole _ with inferred constraints Eq a Show a To use the inferred type enable PartialTypeSignatures ineseheweypersignatunes tor Nas Enumea s as gt gt oleae Gg An extra constraints wildcard can also lead to zero extra constraints to be inferred e g MOG 89 1 22 SEALNE NO SSA NO SS T Or rode ROE Eig gt EELCO RESTA SAO
124. file bar2 Wurble iface with the option ohi bar2 Wurble iface not recommended WARNING if you redirect the interface file somewhere that GHC can t find it then the recompilation checker may get confused at the least you won t get any recompilation avoidance We recommend using a combination of hidir and hisuf options instead if possible To avoid generating an interface at all you could use this option to redirect the interface into the bit bucket ohi dev null for example hidir dir Redirects all generated interface files into dir instead of the default stubdir dir Redirects all generated FFI stub files into dir Stub files are generated when the Haskell source contains a foreign export or foreign import swrapper declaration see Section 8 2 1 The stubdir option behaves in exactly the same way as odir and hidir with respect to hierarchical modules dumpdir dir Redirects all dump files into dir Dump files are generated when dAdump to file is used with other ddump flags outputdir dir The outputdir option is shorthand for the combination of odir hidir stubdir and dum pdir The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 53 327 osuf suffix hisuf suffix hcsuf suffix The osuf suffix will change the o file suffix for object files to whatever you specify We use this when compiling libraries so that objects for the profiling versions of the lib
125. final link of your mixed language application This is not a requirement though just try linking once with v on to see what options the driver passes through to the linker The no hs main flag can also be used to persuade the compiler to do the link step in make mode when there is no Haskell Main module present normally the compiler will not attempt linking when there is no Main The flags rtsopts and with rtsopts have no effect when used with no hs main because they are imple mented by changing the definition of main that GHC generates See Section 8 2 1 1 for how to get the effect of rt sopt s and with rtsopts when using your own main The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 90 327 debug Link the program with a debugging version of the runtime system The debugging runtime turns on numerous assertions and sanity checks and provides extra options for producing debugging output at runtime run the program with RTS to see a list threaded Link the program with the threaded version of the runtime system The threaded runtime system is so called because it manages multiple OS threads as opposed to the default runtime system which is purely single threaded Note that you do not need threaded in order to use concurrency the single threaded runtime supports concurrency between Haskell threads just fine The threaded runtime system provides the following benefits e Itenable
126. flag makes debugging output appear in the more verbose debug style 4 18 2 Formatting dumps dppr user length In error messages expressions are printed to a certain depth with subexpressions beyond the depth replaced by ellipses This flag sets the depth Its default value is 5 dppr colsNNN Set the width of debugging output Use this if your code is wrapping too much For example dppr cols200 dppr case as let Print single alternative case expressions as though they were strict let expressions This is helpful when your code does a lot of unboxing dno debug output Suppress any unsolicited debugging output When GHC has been built with the DEBUG option it occasionally emits debug output of interest to developers The extra output can confuse the testing framework and cause bogus test failures so this flag is provided to turn it off 4 18 3 Suppressing unwanted information Core dumps contain a large amount of information Depending on what you are doing not all of it will be useful Use these flags to suppress the parts that you are not interested in dsuppress all Suppress everything that can be suppressed except for unique ids as this often makes the printout am biguous If you just want to see the overall structure of the code then start here dsuppress uniques Suppress the printing of uniques This may make the printout ambiguous e g unclear where an occurrence of x is bound but it makes the ou
127. fno warn partial type signatures fwarn deriving typeable warn when encountering a request to derive an instance of class Typeable As of GHC 7 10 such declarations are unnecessary and are ignored by the compiler because GHC has a custom solver for discharging this type of constraint dynamic fno warn deriving typeable 4 19 14 Optimisation levels These options are described in more detail in Section 4 10 Flag Description Static Dynamic Reverse 00 Disable optimisations default dynamic 0 0O or 01 Enable level 1 optimisations dynamic 00 02 Enable level 2 optimisations dynamic 00 Odph Enable level 2 optimisations set fmax simplifier iterations 20 and fsimplifier phases 3 dynamic See Section 4 19 15 for a list of optimisations enabled on level 1 and level 2 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 121 327 4 19 15 Individual optimisations These options are described in more detail in Section 4 10 2 If a flag is implied by O then it is also implied by 02 unless flag description explicitly says otherwise If a flag is implied by 00 only then the flag is not implied by 0O and 02 Flag Description Static Dynamic Reverse Enable call arity f
128. fpackage trust flag simply enabling an extra requirement for trustworthy modules to be regarded as trusted 7 29 4 1 Trust check Epackage trust disabled A module M in a package P is trusted by a client C if and only if Both of these hold The module was compiled with XSafe The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 284 327 All of M s direct imports are trusted by C e OR all of these hold The module was compiled with XTrustworthy All of M s direct safe imports are trusted by C The above definition of trust has an issue Any module can be compiled with XTrustworthy and it will be trusted regardless of what it does To control this there is an additional definition of package trust enabled with the fpackage trust flag The point of package trusts is to require that the client C explicitly say which packages are allowed to contain trustworthy modules That is C establishes that it trusts a package P and its author and so trust the modules in P that use XTrustworthy When package trust is enabled any modules that are considered trustworthy but reside in a package that isn t trusted are not considered trusted A more formal definition is given in the next section 7 29 4 2 Trust check fpackage trust enabled When the fpackage trust flag is enabled whether or not a module is trusted depends on a notion of trust for packages which is determined by the client C
129. from arrows may also be used to build commands from commands For example the Ar rowP lus class includes a combinator Arrow lus a At 12 eb e e Aa BoC a ob cS so we can use it to build commands expr proc x gt do return lt x CO symbol Palus lt 0 WS esi 6 EXI lt ar sy lt gt do symbol Minus lt E IN EXP lt x a y The do on the first line is needed to prevent the first lt gt from being interpreted as part of the expression on the previous line This is equivalent to expr proc x gt returnA lt x lt S 970C x CO Syb o EAS E Y lt ein lt The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 254 327 EXI KE sk Sy BOCA Clo symbol Minus lt YS ceil EX We are actually using lt gt here with the more specific type Arrowblus eL Se lt 5 32 ate a gt a ts ts 8 es ec It is essential that this operator be polymorphic in e representing the environment input to the command and thence to its subcommands and satisfy the corresponding naturality property A a SS SE as A a E euas AS LO SS C at least for strict k This should be automatic if you re not using seq This ensures that environments seen by the subcom mands are environments of the whole command and also allows the translation to safely trim these environments The second component of the input pairs can contain unnamed input val
130. gt O data Foo a MkFoo a instance HasConverter a b Show b gt Show Foo a where show MkFoo value show convert value This is dangerous territory however Here for example is a program that would make the typechecker loop class Da class F ab a gt b instance F a mall instance Dc F ac gt D a c is not mentioned in the head Similarly it can be tempting to lift the coverage condition class Mul abc ab gt c where E a gt O gt E instance Mul Int Int Int where x instance Mul Int Float Float where x y fromIntegral x y instance Mul a bc gt Mul a b c where x v map x v The third instance declaration does not obey the coverage condition and indeed the somewhat strange definition i ls y gt ir b then oe yl else y The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 201 327 makes instance inference go into a loop because it requires the constraint Mul a b b Nevertheless GHC allows you to experiment with more liberal rules If you use the experimental flag XUndecidableln stances both the Paterson Conditions and the Coverage Condition described in Section 7 6 3 3 are lifted Termination is ensured by having a fixed depth recursion stack If you exceed the stack depth you get a sort of backtrace and the opportunity to increase the stack depth with fcontext stack NM The XUndecidablelnstances
131. have been optimised away So GHC guarantees to inline precisely the code that you wrote no more and no less It does this by capturing a copy of the definition of the function to use for inlining we call this the inline RHS which it leaves untouched while optimising the ordinarily RHS as usual For externally visible functions the inline RHS not the optimised RHS is recorded in the interface file e An INLINE function is not worker wrappered by strictness analysis It s going to be inlined wholesale instead GHC ensures that inlining cannot go on forever every mutually recursive group is cut by one or more loop breakers that is never inlined see Secrets of the GHC inliner JFP 12 4 July 2002 GHC tries not to select a function with an INLINE pragma as a loop breaker but when there is no choice even an INLINE function can be selected in which case the INLINE pragma is ignored For example for a self recursive function the loop breaker can only be the function itself so an INLINE pragma is always ignored Syntactically an INLINE pragma for a function can be put anywhere its type signature could be put INLINE pragmas are a particularly good idea for the then return or bind unit functions in a monad For example in GHC s own UniqueSuppl y monad code we have The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 263 327 INLINE thenUs INLINE returnUs See
132. how to use internal APIs etc 9 3 4 Typechecker plugins In addition to Core plugins GHC has experimental support for typechecker plugins which allow the behaviour of the constraint solver to be modified For example they make it possible to interface the compiler to an SMT solver in order to support a richer theory of type level arithmetic expressions than the theory built into GHC see Section 7 10 2 The Plugin type has a field tcPlugin of type CommandLineOption gt Maybe TcPlugin where the TcPlugin type is defined thus carta Ieleilvrealin steel s s TOP leia AECE E BCE nMES camlieiasalvs 28 E gt TEPLU ia soler AECE Cn STO 88 Ss gt SEA CMA e type TcPluginSolver Cel Iere gt Ce gt TerPlugiaM Ter lucgamecwlke data TcPluginResult TcPluginContradiction Ct TcPluginOk EvTerm Ct Ct The details of this representation are subject to change as we gain more experience writing typechecker plugins It should not be assumed to be stable between GHC releases The basic idea is as follows e When type checking a module GHC calls tcPluginInit once before constraint solving starts This allows the plugin to look things up in the context initialise mutable state or open a connection to an external process e g an external SMT solver The plugin can return a result of any type it likes and the result will be passed to the other two fields e During constraint solving GHC repeatedly ca
133. in its real definition If you do not write out the constructors you may need to give a kind annotation Section 7 13 5 to tell GHC the kind of the type variable if it is not In source files this is worked out from the way the type variable is used in the constructors For example Glatee I 62 88 E gt Y You cannot use deriving on a data type declaration write an instance declaration instead e Class declarations is exactly as in Haskell except that you may not put default method declarations You can also omit all the superclasses and class methods entirely but you must either omit them all or put them all in e You can include instance declarations just as in Haskell but omit the where part e The default role for class and datatype parameters is now representational To get another role use a role annotation See Section 7 27 4 7 10 Module signatures GHC supports the specification of module signatures which both implementations and users can typecheck against separately This functionality should be considered experimental for now some details especially for type classes and type families may change This system was originally described in Backpack Retrofitting Haskell with Interfaces Signature files are somewhat similar to hs boot files but have the hsig extension and behave slightly differently Suppose that I have modules String hs and A hs thus module Text where data Text Text String
134. in more detail in the paper Giving Haskell a Promotion which appeared at TLDI 2012 7 8 1 Overview of kind polymorphism Currently there is a lot of code duplication in the way Typeable is implemented Section 7 5 4 class Typeable t where typeOf t gt TypeRep class Typeablel t gt x where typeOfl t a gt TypeRep class Typeable2 t gt x gt x where type0f2 t a b gt TypeRep The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 217 327 Kind polymorphism with XPolyKinds allows us to merge all these classes into one data Proxy t Proxy class Typeable t where typeOf Proxy t gt TypeRep instance Typeable Int where typeOf _ TypeRep instance Typeable where typeOf _ TypeRep Note that the datatype Proxy has kind forall k k gt x inferred by GHC and the new Typeable class has kind forall k k gt Constraint 7 8 2 Overview Generally speaking with XPolyKinds GHC will infer a polymorphic kind for un decorated declarations whenever possible For example data Tm a MkT m a GHC infers kind i ge corel Ko CK gt 4 Ie e amp Just as in the world of terms you can restrict polymorphism using a kind signature sometimes called a kind annotation XPolyKinds implies XKindSignatures data Tm a MkT m a GHC now infers kind MS Oe Ce SS i SS ne HS ek There is no forall for kind variables In
135. install the Homebrew package manager for OS X and then install LLVM 3 5 Alternatively you can download binaries for LLVM and Clang from here e Windows You should download binaries for LLVM and clang from here 4 11 3 C Code Generator fvia C This is the oldest code generator in GHC and is generally not included any more having been deprecated around GHC 7 0 Select it with the fvia C flag The C code generator is only supported when GHC is built in unregisterised mode a mode where GHC produces portable C code as output to facilitate porting GHC itself to a new platform This mode produces much slower code though so it s unlikely your version of GHC was built this way If it has then the native code generator probably won t be available You can check this information by calling ghc info 4 11 4 Unregisterised compilation The term unregisterised really means compile via vanilla C disabling some of the platform specific tricks that GHC normally uses to make programs go faster When compiling unregisterised GHC simply generates a C file which is compiled via gcc When GHC is build in unregisterised mode only the LLVM and C code generators will be available The native code generator won t be LLVM usually offers a substantial performance benefit over the C backend in unregisterised mode Unregisterised compilation can be useful when porting GHC to a new machine since it reduces the prerequisite tools to gcc as an
136. interpretation of undefined behaviour in Haskell 98 and Haskell 2010 13 2 Known bugs or infelicities 13 2 1 Bugsin GHC 13 2 2 Bugs in GHCi the interactive GHC o a ee ee 14 Index 303 303 303 305 305 305 305 306 307 307 309 309 309 309 310 310 310 310 310 311 311 312 312 313 314 314 314 314 314 315 315 215 213 316 316 317 s317 oly 318 319 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 xviii The Glasgow Haskell Compiler License Copyright 2002 2007 The University Court of the University of Glasgow All rights reserved Redistribution and use in source and binary forms with or without modification are permitted provided that the following conditions are met e Redistributions of source code must retain the above copyright notice this list of conditions and the following disclaimer e Redistributions in binary form must reproduce the above copyright notice this list of conditions and the following disclaimer in the documentation and or other materials provided with the distribution e Neither name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission THIS SOFTWARE IS PROVIDED BY THE UNIVERSITY COURT OF THE UNIVERSITY OF GLASGOW AND THE CON TRIBUTORS AS IS AND ANY EXPRESS OR IMPLIED WARRANTIES INC
137. invoking GHC i e you A package P is trusted when one of these hold e C s package database records that P is trusted and no command line arguments override this e C s command line flags say to trust P regardless of what is recorded in the package database In either case C is the only authority on package trust It is up to the client to decide which packages they trust When the fpackage trust flag is used a module M from package P is trusted by a client C if and only if Both of these hold The module was compiled with XSafe All of M s direct imports are trusted by C e OR all of these hold The module was compiled with XTrustworthy All of M s direct safe imports are trusted by C Package P is trusted by C For the first trust definition the trust guarantee is provided by GHC through the restrictions imposed by the safe language For the second definition of trust the guarantee is provided initially by the module author The client C then establishes that they trust the module author by indicating they trust the package the module resides in This trust chain is required as GHC provides no guarantee for XTrustworthy compiled modules The reason there are two modes of checking trust is that the extra requirement enabled by fpackage trust causes the design of Safe Haskell to be invasive Packages using Safe Haskell when the flag is enabled may or may not compile depending on the state of trusted p
138. language itself modules names are always fully qualified so you can just think of the fully qualified module name as the module name In particular this means that the full module name must be given after the module keyword at the beginning of the module for example the module A B C must begin module A B C It is a common strategy to use the as keyword to save some typing when using qualified names with hierarchical modules For example Import quialitred Control Monadssth strict as Si For details on how GHC searches for source and interface files in the presence of hierarchical modules see Section 4 7 3 GHC comes with a large collection of libraries arranged hierarchically see the accompanying library documentation More libraries to install are available from HackageDB 7 3 7 Pattern guards The discussion that follows is an abbreviated version of Simon Peyton Jones s original proposal Note that the proposal was written before pattern guards were implemented so refers to them as unimplemented Suppose we have an abstract data type of finite maps with a lookup operation lookup FiniteMap gt Int gt Maybe Int The lookup returns Nothing if the supplied key is not in the domain of the mapping and Just v otherwise where v is the value that the key maps to Now consider the following definition clunky env var var2 okl amp amp ok2 vall val2 Wielierepatise S well a Wee where ml lookup e
139. literal 368 means fromInteger 368 Integer rather than Prelude fromInteger 368 Integer e Fractional literals are handed in just the same way except that the translation is fromRational 3 68 Rational e The equality test in an overloaded numeric pattern uses whatever is in scope e The subtraction operation and the greater than or equal test in n k patterns use whatever and gt are in scope e Negation e g f x means negate f x both in numeric patterns and expressions e Conditionals e g if el then e2 else e3 means if ThenE1se el e2 e3 However case expressions are unaffected e Do notation is translated using whatever functions gt gt gt gt and fail are in scope not the Prelude versions List comprehensions mdo Section 7 3 12 and parallel array comprehensions are unaffected e Arrow notation see Section 7 18 uses whatever arr gt gt gt first app and loop functions are in scope But unlike the other constructs the types of these functions must match the Prelude types very closely Details are in flux if you want to use this ask XRebindableSyntax implies XNoImplicitPrelude In all cases apart from arrow notation the static semantics should be that of the desugared form even if that is a little unexpected For example the static semantics of the literal 368 is exactly that of fromInteger 368 Integer it s fine for fromI nteger to have any
140. lt bj a g 85 a gt Ip xs 22 al GHCi tells us that among other bindings f is in scope However its type is not fully known yet and thus it is not possible to apply it to any arguments Nevertheless observe that the type of its first argument is the same as the type of x and its result type is shared with _result As we demonstrated earlier Section 2 5 1 the debugger has some intelligence built in to update the type of f whenever the types of x or __result are discovered So what we do in this scenario is force x a bit in order to recover both its type and the argument part of f Main gt seq x Main gt print x x 1 We can check now that as expected the type of x has been reconstructed and with it the type of f has been too x Main gt t x x 1 Integer MA fs Integer gt 9 From here we can apply f to any argument of type Integer and observe the results Main gt let b f 10 Main gt t b S gg 19 xMain gt b lt interactive gt 1 0 Ambiguous type variable b in the constraint Slavery Jo uesiSalinve icono a Vee Cie orime Cle lt ilimhecuecieie sl wie gL 8 0 cubas 219 19 tes sa ain gt seq b b Maines tee lo b a Main gt p b DE aver 10 sMa ine t b b Maybe Integer Maime gic I E Integer gt Maybe Integer Main gt 20 Just 20 Manin nies 3 ES Just lp aust 2 dust sp dust 4 Just Al In the first application of f we had to do som
141. lt file gt hp The program hp2ps converts a heap profile as produced by the h lt break down gt runtime option into a PostScript graph of the heap profile By convention the file to be processed by hp2ps has a hp extension The PostScript output is written to lt file gt ps If lt file gt is omitted entirely then the program behaves as a filter hp2ps is distributed in ghc utils hp2ps in a GHC source distribution It was originally developed by Dave Wakeling as part of the HBC LML heap profiler The flags are d In order to make graphs more readable hp2ps sorts the shaded bands for each identifier The default sort ordering is for the bands with the largest area to be stacked on top of the smaller ones The d option causes rougher bands those representing series of values with the largest standard deviations to be stacked on top of smoother ones b Normally hp2ps puts the title of the graph in a small box at the top of the page However if the JOB string is too long to fit in a small box more than 35 characters then hp2ps will choose to use a big box instead The b option forces hp2ps to use a big box e lt float gt in mm pt Generate encapsulated PostScript suitable for inclusion in LaTeX documents Usually the PostScript graph is drawn in landscape mode in an area 9 inches wide by 6 inches high and hp2ps arranges for this area to be ap proximately centred on a sheet of a4 paper This format is convenient of studying
142. make it practical to spawn threads for even tiny pieces of work kesize Default 32k Set the size of stack chunks When a thread s current stack overflows a new stack chunk is created and added to the thread s stack until the limit set by K is reached The advantage of smaller stack chunks is that the garbage collector can avoid traversing stack chunks if they are known to be unmodified since the last collection so reducing the chunk size means that the garbage collector can identify more stack as unmodified and the GC overhead might be reduced On the other hand making stack chunks too small adds some overhead as there will be more overflow underflow between chunks The default setting of 32k appears to be a reasonable compromise in most cases kbsize Default 1k Sets the stack chunk buffer size When a stack chunk overflows and a new stack chunk is created some of the data from the previous stack chunk is moved into the new chunk to avoid an immediate underflow and repeated overflow underflow at the boundary The amount of stack moved is set by the kb option Note that to avoid wasting space this value should typically be less than 10 of the size of a stack chunk kc because in a chain of stack chunks each chunk will have a gap of unused space of this size The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 100 327 Ksize Default 80 physical memory size Set the maximum stack s
143. might be out of date Main gt touch D hs Main gt reload Compiling D D hs interpreted Ok modules loaded A B C D Main gt Note that module D was compiled but in this instance because its source hadn t really changed its interface remained the same and the recompilation checker determined that A B and C didn t need to be recompiled So let s try compiling one of the other modules slcuia gt 24 clas e Colas Main gt load A Compiling D D hs interpreted The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 15 327 Compiling B B hs interpreted Compiling C C hs interpreted Compiling A A hs interpreted Ok modules loaded A B C D We didn t get the compiled version of C What happened Well in GHCi a compiled module may only depend on other compiled modules and in this case C depends on D which doesn t have an object file so GHCi also rejected C s object file Ok so let s also compile D eM Estao 31 Glas e Dolas Main gt reload Ok modules loaded A B C D Nothing happened Here s another lesson newly compiled modules aren t picked up by reload only load Main gt load A Compiling B B hs interpreted Compiling A A hs interpreted Ok modules loaded A B C D The automatic loading of object files can sometimes lead to confusion because non exported top level definitions of a module are only available for u
144. more A regression which could cause the typechecker fail to properly simplify type level terms has been fixed issue 10321 A bug which caused programs compiled with f1late dmd anal to crash at runtime has been fixed issue 10288 A bug which caused ARM Linux binaries to be built with executable stacks has been fixed issue 10369 Several bugs in GHC s cross compilation support using LLVM have been fixed 10275 Several bugs in GHC s support for AArch64 have been fixed such as issue 10264 The SMP runtime and GHCi are now enabled on AArch64 issue 10525 A bug in the code which caused GHC to emit invalid C code when porting to a new platform has been fixed issue 10518 A bug which could cause GHC to generate incorrect code at runtime generating an infinite loop exception has been fixed issue 10218 Several performance related issues inside GHC have been fixed As a result you should see improved compilation times and memory usage issues 10397 10370 10422 A bug which could cause GHCi to crash if exceptions were raised in the cmd command has been fixed A bug in the event manager which could cause multi shot event registrations to only fire once has been fixed issue 10317 Support for PowerPC relocations has been added issue 10402 A lurking bug in the code generator which could cause incorrect assembly code to be generated due to register aliasing issues has been fixed issue 10521 A bug
145. not know more general facts about arithmetic such as the commutativity and associativity of for example However it is possible to perform a bit of backwards evaluation For example here is how we could get GHC to compute arbitrary logarithms at the type level lg ss Bioy basa gt PROA oasa Dow gt BrO DON CA EOS CHEMI POr naval hom BOX ELOY za PrO Vacate PEO SD 9 7 11 Equality constraints A type context can include equality constraints of the form t1 t2 which denote that the types t1 and t2 need to be the same In the presence of type families whether two types are equal cannot generally be decided locally Hence the contexts of function signatures may include equality constraints as in the following example sumtolletis wi Collects el Collects e2 blen l Ele ic gt Ch gt ce gt Ez The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 224 327 where we require that the element type of c1 and c2 are the same In general the types t1 and t2 of an equality constraint may be arbitrary monotypes i e they may not contain any quantifiers independent of whether higher rank types are otherwise enabled Equality constraints can also appear in class and instance contexts The former enable a simple translation of programs using functional dependencies into programs using family synonyms instead The general idea is to rewrite a class declaration of the form class
146. notation it won t make much sense unless you ve read Hughes s paper The extension adds a new kind of expression for defining arrows exp10 poe ajocit scr where proc is a new keyword The variables of the pattern are bound in the body of the proc expression which is a new sort of thing called a command The syntax of commands is as follows cmd expl0 lt exp expl0 lt lt exp ecmdoO with cmd up to cma defined using infix operators as for expressions and cmd10 apat apat gt cmd let decis in cmd if exp then cmd else cmd case exp of calts go l etue y acr este cmd y femd fecemd fcmd aexp ema aso Cal o Gael 1 cstmt let decis bat is tema ee I coume p apro Caie eel cmd where calts are like alts except that the bodies are commands instead of expressions Commands produce values but like monadic computations may yield more than one value or none and may do other things as well For the most part familiarity with monadic notation is a good guide to using commands However the values of expressions even monadic ones are determined by the values of the variables they contain this is not necessarily the case for commands A simple example of the new notation is the expression PEOR El We call this a procedure or arrow abstraction As with a lambda expression the variable x is a new variable bound within the proc expression It refers to the input to the arrow In
147. number of The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 103 327 occurrences of each kind of spark event is sampled at frequent intervals In the fully accurate mode every spark event is logged individually The latter has a higher runtime overhead and is not enabled by default The format of the log file is described by the header Event LogFormat h that comes with GHC and it can be parsed in Haskell using the ghc events library To dump the contents of a event log file as text use the tool ghc events show that comes with the ghc events package v flags Log events as text to standard output instead of to the event log file The flags are the same as for 1 with the additional option t which indicates that the each event printed should be preceded by a timestamp value in the binary event log file all events are automatically associated with a timestamp The debugging options Dx also generate events which are logged using the tracing framework By default those events are dumped as text to stdout Dx implies v but they may instead be stored in the binary eventlog file by using the 1 option 4 17 7 RTS options for hackers debuggers and over interested souls These RTS options might be used a to avoid a GHC bug b to see what s really happening or c because you feel like it Not recommended for everyday use B Sound the bell at the start of each major garbage collec
148. of these directories it tries appending basename extension to the directory and checks whether the file exists The value of basename is the module name with dots replaced by the directory separator or depending on the system and extension is a source extension hs 1hs if we are in make mode or GHCi or hisuf otherwise For example suppose the search path contains directories d1 d2 and d3 and we are in make mode looking for the source file for a module A B C GHC will look in d1 A B C hs d1 A B C 1hs d2 A B C hs and so on 6699 The search path by default contains a single directory gt i e the current directory The following options can be used to add to or change the contents of the search path idirs This flag appends a colon separated list of dirs to the search path i resets the search path back to nothing This isn t the whole story GHC also looks for modules in pre compiled libraries known as packages See the section on packages Section 4 9 for details The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 52 327 4 7 4 Redirecting the compilation output s o file GHC s compiled output normally goes into a hc o etc file depending on the last run compilation phase The option o file re directs the output of that last run phase to file Note this feature can be counterintuitive ghc C o foo o foo hs will put the intermediate
149. only contribute their exports to the current scope To ensure that GHCi loads the interpreted version of a module add the x when loading the module e g load M In general after a Load command an automatic import is added to the scope for the most recently loaded target module in a x form if possible For example if you say load foo hs bar hs and bar hs contains module Bar then the scope will be set to Bar if Bar is interpreted or if Bar is compiled it will be set to Prelude Bar GHCi automatically adds Prelude if it isn t present and there aren t any form modules These automatically added imports can be seen with show imports Prelude gt load hello hs 1 of 1 Compiling Main hello hs interpreted Ok modules loaded Main Main gt show imports module xMain added automatically Main gt and the automatically added import is replaced the next time you use load add or reload It can also be removed by module as with normal imports 2 4 5 2 Controlling what is in scope with import We are not limited to a single module GHCi can combine scopes from multiple modules in any mixture of x and non forms GHCi combines the scopes from all of these modules to form the scope that is in effect at the prompt To add modules to the scope use ordinary Haskell import syntax Prelude gt import System IO Prelude System IO gt hPutStrLn stdout hello n hello Prelude System I0 gt The full Haskel
150. only follow dependencies if it has the source file available so if your program includes a module for which there is no source file even if you have an object and an interface file for the module then GHC will complain The exception to this rule is for package modules which may or may not have source files The source files for the program don t all need to be in the same directory the i option can be used to add directories to the search path see Section 4 7 3 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 48 327 4 5 2 Expression evaluation mode This mode is very similar to interactive mode except that there is a single expression to evaluate which is specified on the command line as an argument to the e option ghc e expr Haskell source files may be named on the command line and they will be loaded exactly as in interactive mode The expression is evaluated in the context of the loaded modules For example to load and run a Haskell program containing a module Main we might say ghc e Main main Main hs or we can just use this mode to evaluate expressions in the context of the Prelude ghc e interact unlines map reverse lines hello olleh 4 5 3 Batch compiler mode In batch mode GHC will compile one or more source files given on the command line The first phase to run is determined by each input file suffix and the last phase is determined by a flag If no relevant f
151. packages are expressed in terms of installed package IDs rather than just packages and versions For example take a look at the dependencies of the haske1198 package The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 71 327 ghc pkg field haskell98 depends depends array 0 2 0 1 9cbf76a576b6ee9c1f880cf171a0928d base 4 2 0 0 247bb20cde37c3ef4093ee124e04bcl1lc directory 1 0 0 2 51711bc872c35ce4a453aal9c799008 old locale 1 0 0 1 d17c9777c8ee53a0d459734e27 2b8e9 old time 1 0 0 1 1c0d8ea38056e5087ef1le75cb0d139d1 process 1 0 1 1 d8fc6 d3baf44678a29b9d59ca0ad5780 random 1 0 0 1 423d08c90 004795fd10e60384ce6561 The purpose of the installed package ID is to detect problems caused by re installing a package without also recompiling the packages that depend on it Recompiling dependencies is necessary because the newly compiled package may have a different ABI Application Binary Interface than the previous version even if both packages were built from the same source code using the same compiler With installed package IDs a recompiled package will have a different installed package ID from the previous version so packages that depended on the previous version are now orphaned one of their dependencies is not satisfied Packages that are broken in this way are shown in the ghc pkg list output either in red if possible or otherwise surrounded by braces In the following example we have recompiled and rei
152. patterns By default the compiler will warn you if a set of patterns are overlapping e g Sin gt Inne EN 0 tf ess 1 E WAEN 2 where the last pattern match in f won t ever be reached as the second pattern overlaps it More often than not redundant patterns is a programmer mistake error so this option is enabled by default fwarn tabs Have the compiler warn if there are tabs in your source file fwarn type defaults Have the compiler warn inform you where in your source the Haskell defaulting mechanism for numeric types kicks in This is useful information when converting code from a context that assumed one default into one with another e g the default default for Haskell 1 4 caused the otherwise unconstrained value 1 to be given the type Int whereas Haskell 98 and later defaults it to Integer This may lead to differences in performance and behaviour hence the usefulness of being non silent about this This warning is off by default fwarn monomorphism restriction Have the compiler warn inform you where in your source the Haskell Monomor phism Restriction is applied If applied silently the MR can give rise to unexpected behaviour so it can be helpful to have an explicit warning that it is being applied This warning is off by default fwarn unticked promoted constructors Warn if a promoted data constructor is used without a tick preceding it s name For example data Nat Succ Nat Zero data Vece n
153. problems running your program 303 problems with the compiler 303 proc 176 profiling 132 options 135 ticky ticky 103 with Template Haskell 248 promoted constructor warning 64 prompt GHCGi 12 Q quasi quotation 177 R reading Core syntax 107 recompilation checker 50 54 record updates incomplete 63 recursion between modules 54 redirecting compilation output 52 reexported modules reexport specification 76 reporting bugs 2 rewrite rules 268 roles 275 RTS 104 RTS behaviour changing 97 RTS hooks 97 RTS options 96 from the environment 97 garbage collection 98 RTS options concurrent 94 RTS options hacking debugging 103 RTS options setting 96 RULES pragma 268 runghc 43 running compiled program 96 runtime control of Haskell programs 96 S safe compilation 287 safe haskell 280 safe haskell flags 286 safe haskell trust 283 safe haskell uses 280 safe imports 283 safe inference 285 safe language 282 sanity checking options 60 search path 51 secure haskell 281 segmentation fault 304 separate compilation 47 50 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 327 327 shadowing interface files 62 shadowing warning 64 Shared libraries using 91 shell commands in GHCi 38 Show class 22 smaller programs how to produce 151 SMP 90 93 94 279 SOURCE 267 source file options 45 space leaks avoiding 151 SPECIALIZ
154. recompiling modules if their external dependencies haven t changed This is the same mechanism we use to avoid re compiling modules in the batch compilation setting see Section 4 7 8 3 Tf you started up GHCi from the command line then GHCi s current directory is the same as the current directory of the shell from which it was started If you started GHCi from the Start menu in Windows then the current directory is probably something like C Documents and Settings user name 4 Note that in GHCi and make mode the i option is used to specify the search path for source files whereas in standard batch compilation mode the i option is used to specify the search path for interface files see Section 4 7 3 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 14 327 2 3 Loading compiled code When you load a Haskell source module into GHCi it is normally converted to byte code and run using the interpreter However interpreted code can also run alongside compiled code in GHCi indeed normally when GHCi starts it loads up a compiled copy of the base package which contains the Prelude Why should we want to run compiled code Well compiled code is roughly 10x faster than interpreted code but takes about 2x longer to produce perhaps longer if optimisation is on So it pays to compile the parts of a program that aren t changing very often and use the interpreter for the code being actively dev
155. recursive bindings in a module it compiles module SayNames Plugin plugin where import GhcPlugins Dbue sg Bic plugin defaultPlugin The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 300 327 installCoreToDos install install CommandLineOption gt CoreToDo gt CoreM CoreToDo install todo do reinitializeGlobals return CoreDoPluginPass Say name pass todo pass ModGuts gt CoreM ModGuts pass guts do dflags lt getDynFlags bindsOnlyPass mapM printBind dflags guts where printBind DynFlags gt CoreBind gt CoreM CoreBind printBind dflags bndr NonRec b _ do putMsgS Non recursive binding named showSDoc dflags ppr b return bndr printBind _ bndr return bndr 9 3 3 2 Using Annotations Previously we discussed annotation pragmas Section 9 1 which we mentioned could be used to give compiler plugins extra guidance or information Annotations for a module can be retrieved by a plugin but you must go through the modules ModGut s in order to get it Because annotations can be arbitrary instances of Data and Typeable you need to give a type annotation specifying the proper type of data to retrieve from the interface file and you need to make sure the annotation type used by your users is the same one your plugin uses For this reason we advise distributing annotations as part of the package which also provides compiler plugins if possible
156. ring is the name of the function that was called and the SrcLoc provides the package module and file name as well as the line and column numbers The stack will never be empty as the first call site will be the location at which the implicit parameter was used GHC will also never infer loc CallStack as a type constraint which means that functions must explicitly ask to be told about their call sites A potential gotcha when using implicit CallStacks is that the type command in GHCi will not report the loc CallStack constraint as the typechecker will immediately solve it Use info instead to print the unsolved type 7 13 5 Explicitly kinded quantification Haskell infers the kind of each type variable Sometimes it is nice to be able to give the kind explicitly as machine checked documentation just as it is nice to give a type signature for a function On some occasions it is essential to do so For example in his paper Restricted Data Types in Haskell Haskell Workshop 1999 John Hughes had to define the data type data Set cxt a Set a sea Text a gt O The only use for the Unused constructor was to force the correct kind for the type variable cxt GHC now instead allows you to specify the kind of a type variable directly wherever a type variable is explicitly bound with the flag XKindSignatures This flag enables kind signatures in the following places e data declarations dato Sel Weel 21 gt ey a
157. should be OK if just one has this form and the others are type variables but that s the rules at the moment GHC relaxes this rule in two ways e With the XTypeSynonymInstances flag instance heads may use type synonyms As always using a type synonym is just shorthand for writing the RHS of the type synonym definition For example type Point a a a instance C Point a where is legal The instance declaration is equivalent to instance C a a where As always type synonyms must be fully applied You cannot for example write instance Monad Point where The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 199 327 e The XFlexiblelnstances flag allows the head of the instance declaration to mention arbitrary nested types For exam ple this becomes a legal instance declaration instance C Maybe Int where See also the rules on overlap The XFlexiblelnstances flag implies XTypeSynonymInstances 7 6 3 3 Relaxed rules for instance contexts In Haskell 98 the assertions in the context of the instance declaration must be of the form C a where a is a type variable that occurs in the head The XFlexibleContexts flag relaxes this rule as well as the corresponding rule for type signatures see Section 7 13 2 With this flag the context of the instance declaration can each consist of arbitrary well kinded assertions C t1 tn subject only to the following rules 1 The Paterson Conditi
158. something like this Prelude gt seti base language is Haskel12010 with the following modifiers XNoMonomorphismRestriction XNoDatatypeContexts The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 40 327 XNondecreasingIndentation XExtendedDefaultRules GHCi specific dynamic flag settings other dynamic non language flag settings fimplicit import qualified warning settings The two sets of options are initialised as follows First both sets of options are initialised as described in Section 2 9 Then the interactive options are modified as follows e The option XExtendedDefaultRules is enabled in order to apply special defaulting rules to expressions typed at the prompt see Section 2 4 8 e The Monomorphism Restriction is disabled see Section 7 13 9 1 2 9 The ghci file When it starts unless the ignore dot ghci flag is given GHCi reads and executes commands from the following files in this order if they exist L ghci 2 appdata ghc ghci conf where appdata depends on your system but is usually something like C Document s and Settings user Application Data 3 On Unix SHOME ghc ghci conf 4 SHOME ghci The ghci conf file is most useful for turning on favourite options eg set s and defining useful macros Note when setting language options in this file it is usually desirable to use set i rather than set see Section 2 8 3 Placing
159. spelled the same as the field name e Puns and other patterns can be mixed in the same record data C Co an Fe a ee ee ECO 4 a e Puns can be used wherever record patterns occur e g in Let bindings or at the top level e A pun on a qualified field name is expanded by stripping off the module qualifier For example f C M a a means E MIG Mea a a This is useful if the field selector a for constructor M C is only in scope in qualified form 7 3 24 Record wildcards Record wildcards are enabled by the flag KRecordWildCards This flag implies XDisambiguateRecordFields For records with many fields it can be tiresome to write out each field individually in a record pattern as in AA A o a a a a By Or ao UL CAS iy 19 y Gy el d o ap E 0l Record wildcard syntax permits a in a record pattern where each elided field f is replaced by the pattern f f For example the above pattern can be written as E E ta o oo 19 3 10 ap cl More details The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 174 327 e Record wildcards in patterns can be mixed with other patterns including puns Section 7 3 23 for example in a pattern C la 1 b Additionally record wildcards can be used wherever record patterns occur including in let bindings and at the top level For example the top level binding C la l e defines b c and d e Record
160. strongly that any of these restrictions are too onerous please give the GHC team a shout 9 3 1 Using compiler plugins Plugins can be specified on the command line with the option fplugin module where module is a module in a registered package that exports a plugin Arguments can be given to plugins with the command line option fplugin opt module args where args are arguments interpreted by the plugin provided by module As an example in order to load the plugin exported by Foo Plugin in the package foo ghc plugin and give it the parameter baz we would invoke GHC like this ghc fplugin Foo Plugin fplugin opt Foo Plugin baz Test hs 1 of 1 Compiling Main Test hs Test o Loading package ghc prim linking done Loading package integer gmp linking done Loading package base linking done ih adsunGe packagers righ Oe psmleienikebniGaaenen mC One loadings packagemroo ghe piliigasme Ore Mare One Linking Test Since plugins are exported by registered packages it s safe to put dependencies on them in cabal for example and specify plugin arguments to GHC through the ghc options field 9 3 2 Writing compiler plugins Plugins are modules that export at least a single identifier plugin of type GhcPlugins Plugin All plugins should import GhcPlugins as it defines the interface to the compilation pipeline A Plugin effectively holds a function which installs a compilation pass into the c
161. supply the extra input required by commands built with the last two by applying them to ordinary expressions as in procki clo s lt ltunbeader do fil Ss which adds s to the stack of inputs to the command built using runReader The command versions of lambda abstraction and application are analogous to the expression versions In particular the beta and eta rules describe equivalences of commands These three features operators lambda abstraction and application are the core of the notation everything else can be built using them though the results would be somewhat clumsy For example we could simulate do notation by defining bind Arrow a gt a e s b gt a e b s c gt a e s c il Moshe Ge ieSieibliainv in il Se Ge banel g3 Arcon E gt a 6 8 le gt a Ge e gt a le e w bind w bind fare Est E We could simulate if by defining cond ArrowChoice a gt a e s b gt a e s b gt a e Bool s D Coincl 3 G aie 6 oe S gt air lp telagin ene 2 5 lse Right e s gt E e 7 18 5 Differences with the paper e Instead of a single form of arrow application arrow tail with two translations the implementation provides two forms lt first order and lt lt higher order e User defined operators are flagged with banana brackets instead of a new form keyword e In the paper and the previous implementation value
162. t case v of pat gt e _ gt e y sec casa y or I pate gt ep _ gt That leaves let expressions whose translation is given in Section 3 12 of the Haskell Report In the translation box first apply the following transformation for each pattern pi that is of form qi ei transform it to xi qi ei and replace e0 by xi seq e0 Then when none of the left hand side patterns have a bang at the top apply the rules in the existing box The effect of the let rule is to force complete matching of the pattern qi before evaluation of the body is begun The bang is retained in the translated form in case qi is a variable thus let ly f x in b The let binding can be recursive However it is much more common for the let binding to be non recursive in which case the following law holds let p rhs in body is equivalent to case rhs of p gt body A pattern with a bang at the outermost level is not allowed at the top level of a module The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 258 327 7 20 Assertions If you want to make use of assertions in your standard Haskell code you could define a function like the following asssre 328 BOOL gt a gt A assert False x error assertion failed assert _ x X which works but gives you back a less than useful error message an assertion failed but which and where One way out is to define an extended assert fu
163. that are searched left to right for packages If GHC_PACKAGE_PATH ends in a separator then the default package database stack i e the user and global package databases in that order is appended For example to augment the usual set of packages with a database of your own you could say on Unix export GHC_PACKAGE_PATH HOME my ghc packages conf use instead of on Windows To check whether your GHC_PACKAGE_PATH setting is doing the right thing ghc pkg list will list all the databases in use in the reverse order they are searched 4 9 6 Installed package IDs dependencies and broken packages Each installed package has a unique identifier the installed package ID which distinguishes it from all other installed pack ages on the system To see the installed package IDs associated with each installed package use ghc pkg list v omeneko list Y using cache usr lib ghc 6 12 1 package conf d package cache usr lib ghc 6 12 1 package conf d Cabal 1 7 4 Cabal 1 7 4 48f5247e06853af93593883240e11238 array 0 2 0 1 array 0 2 0 1 9cbf76a576b6ee9c1f880cf171a0928d base 3 0 3 base 3 0 3 0 6cbb157b9ae852096266e113b8fac4a2 base 4 2 0 base 4 2 0 0 247bb20cde37c3ef4093ee124e04bc1c 0 0 The string in parentheses after the package name is the installed package ID it normally begins with the package name and version and ends in a hash string derived from the compiled package Dependencies between
164. that can make runtime or space worse if you re unlucky They are normally turned on or off individually At the moment 02 is unlikely to produce better code than O Odph Enables all O2 optimisation sets fmax simplifier iterations 20 and fsimplifier phases 3 Designed for use with Data Parallel Haskell DPH We don t use a Ox flag for day to day work We use O to get respectable speed e g when we want to measure something When we want to go for broke we tend to use 02 and we go for lots of coffee breaks The easiest way to see what O etc really mean is to run with v then stand back in amazement 4 10 2 x platform independent flags These flags turn on and off individual optimisations Flags marked as Enabled by default are enabled by O and as such you shouldn t need to set any of them explicitly A flag fwombat can be negated by saying fno wombat See Section 4 19 15 for a compact list fcase merge On by default Merge immediately nested case expressions that scrutinse the same variable Example case x of Red gt el gt case x of Blue gt e2 Green gt e3 gt case x of Red gt el Blue gt e2 Green gt e2 fcall arity On by default fcmm elim common blocks On by default Enables the common block elimination optimisation in the code generator This optimisation attempts to find identical Cmm blocks and eliminate the duplicates fcmm sink On by
165. the above example lt is not an identifier but an new reserved symbol used for building commands from an expression of arrow type and an expression to be fed as input to that arrow The weird look will make more sense later It may be read as analogue of application for arrows The above example is equivalent to the Haskell expression cua e seb SSS tc The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 252 327 That would make no sense if the expression to the left of lt involves the bound variable x More generally the expression to the left of lt may not involve any local variable i e a variable bound in the current arrow abstraction For such a situation there is a variant lt lt as in ISOS Sh 3 Se E ll which is equivalent to arr x gt E seril SSS and so in this case the arrow must belong to the ArrowAppl y class Such an arrow is equivalent to a monad so if you re using this form you may find a monadic formulation more convenient 7 18 1 do notation for commands Another form of command is a form of do notation For example you can write proe z gt clo y lt E lt ll g lt 2xy let z x y i lt 11 Es returnA lt t z You can read this much like ordinary do notation but with commands in place of monadic expressions The first line sends the value of x 1 as an input to the arrow f and matches its output against y In the next line the o
166. the following syntax pattern Head x lt x xs In this case Head x cannot be used in expressions only patterns since it wouldn t specify a value for the xs on the right hand side We can give an explicit inversion of a pattern synonym using the following syntax pattern Head x lt x xs where Head x x The syntax and semantics of pattern synonyms are elaborated in the following subsections See the Wiki page for more details 7 3 9 1 Syntax and scoping of pattern synonyms A pattern synonym declaration can be either unidirectional or bidirectional The syntax for unidirectional pattern synonyms is pattern Name args lt pat and the syntax for bidirectional pattern synonyms is pattern Name args pat or pattern Name args lt pat where Name args expr Either prefix or infix syntax can be used Pattern synonym declarations can only occur in the top level of a module In particular they are not allowed as local definitions The variables in the left hand side of the definition are bound by the pattern on the right hand side For implicitly bidirectional pattern synonyms all the variables of the right hand side must also occur on the left hand side also wildcard patterns and view patterns are not allowed For unidirectional and explicitly bidirectional pattern synonyms there is no restriction on the right hand side pattern Pattern synonyms cannot be defined recursively 7 3 9 2 Import and export of pattern sy
167. the last complete sample using tail and cut This is used as a parameter to head the result is as if we deleted the final incomplete sample from FOO hp This results in a properly formatted hp file which we feed directly to hp2ps 5 5 4 Viewing a heap profile in real time The gv and ghostview programs have a watch file option can be used to view an up to date heap profile of your program as it runs Simply generate an incremental heap profile as described in the previous section Run gv on your profile gv watch seascape FOO ps If you forget the wat ch flag you can still select Watch file from the State menu Now each time you generate a new profile FOO ps the view will update automatically This can all be encapsulated in a little script bin sh keddi ME rep O ENDESA MEE O EA SU SO ON hp2ps gt FOO ps gv watch seascape FOO ps amp wade 1 3 do sleep 10 We generate a new profile every 10 seconds head fgrep n END_SAMPLE FOO hp tail 1 cut d f 1 FOO hp A hp2ps gt FOO ps done Occasionally gv will choke as it tries to read an incomplete copy of FOO ps because hp2ps is still running as an update occurs A slightly more complicated script works around this problem by using the fact that sending a SIGHUP to gv will cause it to re read its input file bin sh head fgrep n END_SAMPLE FOO hp tail 1 cut d f 1 FOO hp hp2ps gt FOO ps gv FOO ps amp gvps
168. the scoping rules Hence to mention a non Prelude type or class you must import it e There must be no value declarations but there can be type signatures for values For example clotlolle 5 Mate Joie e Fixity declarations are exactly as in Haskell e Vanilla type synonym declarations are exactly as in Haskell e Open type and data family declarations are exactly as in Haskell The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 56 327 e A closed type family may optionally omit its equations as in the following example type family ClosedFam a where The is meant literally you should write two dots in your file Note that the where clause is still necessary to distinguish closed families from open ones If you give any equations of a closed family you must give all of them in the same order as they appear in the accompanying Haskell file e A data type declaration can either be given in full exactly as in Haskell or it can be given abstractly by omitting the sign and everything that follows For example data Tab In a source program this would declare TA to have no constructors a GHC extension see Section 7 4 1 but in an hi boot file it means I don t know or care what the constructors are This is the most common form of data type declaration because it s easy to get right You can also write out the constructors but if you do so you must write it out precisely as
169. to be INLINEd esp monads Placing INLINE pragmas on certain functions that are used a lot can have a dramatic effect See Section 7 22 6 1 Explicit export list If you do not have an explicit export list in a module GHC must assume that everything in that module will be exported This has various pessimising effects For example if a bit of code is actually unused perhaps because of unfolding effects GHC will not be able to throw it away because it is exported and some other module may be relying on its existence GHC can be quite a bit more aggressive with pieces of code if it knows they are not exported Look at the Core syntax The form in which GHC manipulates your code Just run your compilation with ddump simp1 don t forget the 0 If profiling has pointed the finger at particular functions look at their Core code let s are bad cases are good dictionar ies d lt Class gt lt Unique gt or anything overloading ish are bad nested lambdas are bad explicit data constructors are good primitive operations e g eqInt are good Use strictness annotations Putting a strictness annotation on a constructor field helps in two ways it adds strictness to the program which gives the strictness analyser more to work with and it might help to reduce space leaks It can also help in a third way when used with funbox strict fields see Section 4 10 2 a strict field can be unpacked or unboxed in the cons
170. to promotion e We promote data types and newt ypes but not type synonyms or type data families Section 7 7 e We only promote types whose kinds are of the form gt gt gt x In particular we do not promote higher kinded datatypes such as data Fix f In f Fix f or datatypes whose kinds involve promoted types such as Vec gt Nat gt x e We do not promote data constructors that are kind polymorphic involve constraints mention type or data families or involve types that are not promotable The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 221 327 7 9 3 Distinguishing between types and constructors Since constructors and types share the same namespace with promotion you can get ambiguous type names data P il data Prom P E type T P AO EA omo ES AZ In these cases if you want to refer to the promoted constructor you should prefix its name with a quote type T1 2 type T2 P promoted es Note that promoted datatypes give rise to named kinds Since these can never be ambiguous we do not allow quotes in kind names Just as in the case of Template Haskell Section 7 17 1 there is no way to quote a data constructor or type constructor whose second character is a single quote 7 9 4 Promoted list and tuple types With XDataKinds Haskell s list and tuple types are natively promoted to kinds and enjoy the same convenient syntax at the type
171. top level function entry counts highlight covered code path to write output to hs files mix files rather that code gaps hpc sum adds together any number of t ix files into a single t ix file hpc sum does not change the original t ix file it generates anew tix file hpc help sum Usage hpc sum Sum multiple Options exclude PACKAGI include PACKAGI OCUPE EA union OPTION tix files in a single ry intersection 5 7 3 4 hpc combine hpc combine is the swiss army knife of hpc It can be used to take the difference between MODUL lt TIX_FILE gt a MODULI pa tix file exclude MODULE lt TIX_FILE gt include MODULE T ES OWENE ils use the union of th lt TIX_FILE gt and or PACKAG and or PACKAG jes Je modul default is lt lt namespac tix files to subtract one tix file from another or to add two t ix files hpc combine does not change the original t ix file it generates a new tix file hpc help combine Usage Combine two Options exclude PACKAGI include PACKAGI SOU oe bl UA Cito union hpc combine tix files in a single OPTION Eh UNCTION intersection 5 7 3 5 hpc map MODU lt TIX_FILI MODU esos sea ikea exclude MODULE include MODULI Cutout BILE
172. type have the same name GHCi will treat them as distinct For example The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 19 327 Prelude gt data T A B Prelude gt let f A True f B False Prelude gt data T A B C Prelude gt f A lt interactive gt 2 3 Couldn t match expected type main Interactive T with actual type T In the first argument of f namely A In the expression f A an a Sequencaioln moje itis alte TE A Prelude gt The old shadowed version of T is displayed as main Interactive T by GHCi in an attempt to distinguish it from the new T which is displayed as simply T Class and type family instance declarations are simply added to the list of available instances with one exception Since you might want to re define one a class or type family instance replaces any earlier instance with an identical head or left hand side respectively See Section 7 7 2 4 5 What s really in scope at the prompt When you type an expression at the prompt what identifiers and types are in scope GHCi provides a flexible way to control exactly how the context for an expression is constructed e The load add and reload commands Section 2 4 5 1 e The import declaration Section 2 4 5 2 e The module command Section 2 4 5 3 The command show imports will show a summary of which modules contribute to the top level scope Hint GHCi will ta
173. types all of the IntXX and WordXX types Ratio a Float and Double e All Template Haskell datatypes now have Generic and Ord instances e Ppr instances were added for Lit and Loc The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 6 327 1 1 1 Two new declaration forms are now supported standalone deriving declarations and generic method signatures written using default inaclass This means an expansion to the Dec type Template Haskell is now more pedantic about splicing in bogus variable names like those containing whitespace If you use bogus names in your Template Haskell code this may break your program 5 2 5 Runtime system The linker API is now thread safe The main user facing impact of this change is that you must now call initLinker before calling LoadObj or any of the other linker APIs 5 2 6 Build system ghc pkg now respects user and global when modifying packages e g changing exposed trust flag or unregister ing Previously ghc pkg would ignore these flags and modify whichever package it found first on the database stack To recover the old behavior simply omit these flags ghc pkg accepts a user package db flag which allows a user to override the location of the user package database Unlike databases specified using package db a user package database configured this way respects the user flag 5 2 7 Package system ghc pkg and ghc have droppe
174. types or type synonym families However data families are generally allowed and type synonyms are allowed as long as they are fully applied and expand to a type that is admissible these are the exact same requirements as for data instances For example the e instance for Elem is type instance Elem e Type family instance declarations are only legitimate when an appropriate family declaration is in scope just like class instances require the class declaration to be visible Moreover each instance declaration has to conform to the kind determined by its family declaration and the number of type parameters in an instance declaration must match the number of type parameters in the family declaration Finally the right hand side of a type instance must be a monotype i e it may not include foralls and after the expansion of all saturated vanilla type synonyms no synonyms except family synonyms may remain 7 7 2 3 Closed type families A type family can also be declared with a where clause defining the full set of equations for that family For example type family F a where F Int Double T BOOL Chiara Fa String A closed type family s equations are tried in order from top to bottom when simplifying a type family application In this example we declare an instance for F such that F Int simplifies to Double F Bool simplifies to Char and for any other type a that is known not to be Int or Bool F a simplifies to
175. use of unboxed types and unboxed tuples which we briefly summarise here 7 2 1 Unboxed types Most types in GHC are boxed which means that values of that type are represented by a pointer to a heap object The represen tation of a Haskell Int for example is a two word heap object An unboxed type however is represented by the value itself no pointers or heap allocation are involved Unboxed types correspond to the raw machine types you would use in C Int long int Double double Addr void etc The primitive operations PrimOps on these types are what you might expect e g is addition on Int s and is the machine addition that we all know and love usually one instruction Primitive unboxed types cannot be defined in Haskell and are therefore built into the language and compiler Primitive types are always unlifted that is a value of a primitive type cannot be bottom We use the convention but it is only a convention that primitive types values and operations have a suffix see Section 7 3 2 For some primitive types we have special syntax for literals also described in the same section Primitive values are often represented by a simple bit pattern such as Int Float Double But this is not necessarily the case a primitive value might be represented by a pointer to a heap allocated object Examples include Array the type of primitive arrays A primitive arr
176. wildcards can also be used in an expression when constructing a record For example let a wenig 25 C ae el UG ou ee Bares in place of let a Ip i9 a e S Kel 4 in C a a b b c c d d The expansion is purely syntactic so the record wildcard expression refers to the nearest enclosing variables that are spelled the same as the omitted field names e Record wildcards may not be used in record updates For example this is illegal e For both pattern and expression wildcards the expands to the missing in scope record fields Specifically the expansion of C includes f if and only if f is a record field of constructor C The record field f is in scope somehow either qualified or unqualified In the case of expressions but not patterns the variable f is in scope unqualified apart from the binding of the record selector itself These rules restrict record wildcards to the situations in which the user could have written the expanded version For example module M where clara RS 1 E o e module X where import M R a c dd ss The R expands to R M a a omitting b since the record field is not in scope and omitting c since the variable c is not in scope apart from the binding of the record selector c of course e Record wildcards cannot be used a in a record update construct and b for data constructors that are not declared with record fields For example f x x
177. written infix very much like expressions More specifically e A type constructor or class can be an operator beginning with a colon e g x The lexical syntax is the same as that for data constructors e Data type and type synonym declarations can be written infix parenthesised if you want further arguments E g data a b Foo a b type a b Either a b class a b where data a b x Baz ab x evo a Sms 19 y midier alo Y The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 178 327 e Types and class constraints can be written infix For example Be pe iat SiR BOO tos la bb a gt bD e Back quotes work as for expressions both for type constructors and type variables e g Int Either Bool or Int a Bool Similarly parentheses work the same e g Int Bool e Fixities may be declared for type constructors or classes just as for data constructors However one cannot distinguish between the two in a fixity declaration a fixity declaration sets the fixity for a data constructor and the corresponding type constructor For example aoee aol Ti A sets the fixity for both type constructor T and data constructor T and similarly for Int a Bool e Function arrow is infixr with fixity O This might change I m not sure what it should be 7 4 4 Type operators In types an operator symbol like is normally treated as a type va
178. x of 5 We much prefer B Why Because GHC can figure out that True False is an empty type So B has no partiality and GHC should be able to compile with fwarn incomplete patterns Though the pattern match checking is not yet clever enough to do that On the other hand A looks dangerous and GHC doesn t check to make sure that in fact the function can never get called 7 3 21 Multi way if expressions With XMultiWaylf flag GHC accepts conditional expressions with multiple branches ae guari gt exami sce guardN gt exprN which is roughly equivalent to case of 2 Pouendis gt expr guardN gt exprN Multi way if expressions introduce a new layout context So the example above is equivalent to be quemeil exori cs guardN gt exprN The following behaves as expected aie cuarcil gt ii cuerda gt que guard3 gt expr3 guard4 gt expr4 because layout translates it as The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 172 327 Le cjuevscil gt dit guare gt Sxgoier guard3 gt expr3 p guard4 gt expr4 Layout with multi way if works in the same way as other layout contexts except that the semi colons between guards in a multi way if are optional So it is not necessary to line up all the guards at the same column this is consistent with the way guards work in function definitions and cas
179. you can set the reverse option Prelude gt set fno warn incomplete patterns XNoMultiParamTypeClasses Section 4 19 lists the reverse for each option where applicable Certain static options package I i and 1 in particular will also work but some may not take effect until the next reload 2 8 3 Setting options for interactive evaluation only GHCi actually maintains two sets of options e The loading options apply when loading modules e The interactive options apply when evaluating expressions and commands typed at the GHCi prompt The set command modifies both but there is also a seti command for set interactive that affects only the interactive options set It is often useful to change the interactive options without having that option apply to loaded modules too For example seti XMonoLocalBinds It would be undesirable if KMonoLocalBinds were to apply to loaded modules too that might cause a compilation error but more commonly it will cause extra recompilation because GHC will think that it needs to recompile the module because the flags have changed If you are setting language options in your ghci file it is good practice to use set i rather than set unless you really do want them to apply to all modules you load in GHCi The two sets of options can be inspected using the set and seti commands respectively with no arguments For example in a clean GHCi session we might see
180. you interrupt a running program inside GHCi as it should This problem is caused by the fact that the Cygwin and MSYS shell environments don t pass Control C events to non Cygwin child processes because in order to do that there needs to be a Windows console There s an exception you can use a Cygwin shell if the CYGWIN environment variable does not contain tt y In this mode the Cygwin shell behaves like a Windows console shell and console events are propagated to child processes Note that the CYGWIN environment variable must be set before starting the Cygwin shell changing it afterwards has no effect on the shell This problem doesn t just affect GHCi it affects any GHC compiled program that wants to catch console events See the GHC ConsoleHandler module 12 3 Interacting with the terminal By default GHC builds applications that open a console window when they start If you want to build a GUI only application with no console window use the flag opt 1 mwindows in the link step Warning Windows GUI only programs have no stdin stdout or stderr so using the ordinary Haskell input output functions will cause your program to fail with an IO exception such as Fail lt stdout gt hPutChar failed Bad file descriptor The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 310 327 However using Debug Trace trace is alright because it uses Windows debugging output support rather than stderr For s
181. 10 2 119 327 Flag Description Static Dynamic Reverse fwarn fno warn nrecognised Wart OON BASN O prae TiS dynamic nrecognised u a 3 u i A that GHC doesn t recognise y a pragmas pragmas fwarn unticked fno warn warn if promoted 5 promoted dynamic unticked promoted constructors are not ticked constructors constructors fwarn unused warn about bindings that fno warn unused dynamic f binds are unused binds fwarn unused warn about unnecessary 7 fFno warn unused A dynamic imports imports imports fwarn unused warn about variables in fno warn unused A dynamic matches patterns that aren t used matches warn about do bindings that A fwarn unused do a fno warn unused appear to throw away values dynamic A bind do bind of types other than warn about do bindings that fwarn wrong do appear to throw away fno warn wrong dynamic bind monadic values that you do bind should have bound instead warn if the module being compiled is regarded to be unsafe Should be used to check the safety status of modules when using safe inference Works on all fwarn unsaf module types even those dynamic fno warn unsaf using explicit Safe Haskell modes such as XTrustworthy and so can be used to have the compiler check any assumptions made warn if the module being compiled is regarded to be safe Should be used to check the safety stat
182. 17 1 1 e at compile time using with rtsopts Section 4 17 1 2 e with the environment variable GHCRTS Section 4 17 1 3 e by overriding hooks in the runtime system Section 4 17 1 4 4 17 1 1 Setting RTS options on the command line If you set the rt sopts flag appropriately when linking see Section 4 12 6 you can give RTS options on the command line when running your program When your Haskell program starts up the RTS extracts command line arguments bracketed between RTS and RTS as its own For example SEqhewprogahse rtsoptas 1 of 1 Compiling Main Mp uo gas PEOR ansia EOS coo SI O SOS SS h 00 bar The RTS will snaffle H32m S for itself and the remaining arguments f h foo bar will be available to your program if when it calls System Environment getArgs No RTS option is required if the runtime system options extend to the end of the command line as in this example hls ltr usr etc RIS A5m If you absolutely positively want all the rest of the options in a command line to go to the program and not the RTS use a RTS As always for RTS options that take sizes If the last character of size is a K or k multiply by 1000 if an M or m by 1 000 000 if a G or G by 1 000 000 000 And any wraparound in the counters is your fault Giving a RTS option will print out the RTS options actually available in your program which vary depending on how you compiled NOTE since GH
183. 256626 cocos ranma A ee 6 15 3 Libraries 4448 dde e dd AL a di SES 6 1 53 armay A AAN 6 L332 DASS ERA A As A oe 6 1 5 3 3 gt bin package db a6 6 eck Pas a a o a A amp ao F 1534 Diay ceca g epa e e e ee Oa A ee 7 LID ytesting s srai bok be el Se me a RA e A E e da yi 153 0 Cabale cis e a Be See EM Re ee ee Be cos Pe e EE ES z 1523 7 Containers osupa E A Bete ewe west MESS eee oe ee owe he 4 7 153 8 deSpS qy 2 cm aer a aa da eA eo Oe J 1 5 3 9 difectOly seamos e A eS EASA ewe A ee 7 1 5 3 10 filepath 3 04 3 2 bo ae takes ead baw ae oh Se ba Be Be Be we a T IS BOC ene oe NA AN E RA tr TE q SSL POP te e AAA AR oe 7 5 3 03 haskelme 2 ac pope ere e oe Oe e a a a Ee we Se a E 8 15 354 hoopl coser ida A ia A 8 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 iv 1 93 05 PC 4 ee ake be ee e ee he eee a a a Oe wee 8 1 5 3 16 integet gmp 0564 25a eee eR EMR OR ER ee a OE we a 8 1 5317 pretty a0 ss eee eM a Ew a be RS a be ea ea Pe 8 1 5 3 18 PIOCESS ts ne see eS ap e Pa eg ak a BOG BD bog a A Bal go e 8 1 5 3 19 template haskell o s se ee ee ee ee 8 1 53 20 ACHING fhe a ee ee A ee a Se OR EE Ae ee eS 8 A A ANN Hes Ghee dee G 8 1 5 3 22 transformers lt 2 4 eae eee DORA eb ee ee eee eee 8 933 23 UNIK co oe ecko Sos Bk Be a Se a ee ee SN te We Oe e we 8 1 33 24 WiN 2 ts eee Bets we eh oh as enh Boe Wis GA edi we S 9 133 23 Al tos bans bo See eH EE Ee a
184. 4 13 Using shared libraries On some platforms GHC supports building Haskell code into shared libraries Shared libraries are also sometimes known as dynamic libraries in particular on Windows they are referred to as dynamic link libraries DLLs Shared libraries allow a single instance of some pre compiled code to be shared between several programs In contrast with static linking the code is copied into each program Using shared libraries can thus save disk space They also allow a single copy of code to be shared in memory between several programs that use it Shared libraries are often used as a way of structuring large projects especially where different parts are written in different programming languages Shared libraries are also commonly used as a plugin mechanism by various applications This is particularly common on Windows using COM In GHC version 6 12 building shared libraries is supported for Linux on x86 and x86 64 architectures GHC version 7 0 adds support on Windows see Section 12 6 FreeBSD and OpenBSD x86 and x86 64 Solaris x86 and Mac OS X x86 and PowerPC Building and using shared libraries is slightly more complicated than building and using static libraries When using Cabal much of the detail is hidden just use nable shared when configuring a package to build it into a shared library or to link it against other packages built as shared libraries The additional complexity when building code is to distinguish whe
185. 5 128 pgmL 85 128 pgmP 85 128 pgma 85 128 pgmc 85 128 pgmdll 85 128 pgml 85 128 pgmlc 85 128 pgmlibtool 85 pgmlo 85 128 pgms 85 pgmwindres 85 prof 135 248 qbRTS option 99 qgRTS option 99 r RTS option 103 rdynamic 91 rtsopts 90 291 S RTS option 100 shared 89 311 split objs 89 static 89 staticlib 88 stubdir 52 t RTS option 100 this package key 68 threaded 90 tmpdir 53 tmpdir lt dir gt option 53 trust 68 user package db 70 v 49 148 ghc pkg option 74 RTS option 103 w 61 with rtsopts 90 x 48 XC RTS option 103 136 xm RTS option 97 xq RTS option 98 Xt RTS option 138 ghci file 40 hc files saving 53 hi files 50 ll files saving 53 o files 50 S files saving 53 33 1 38 R abandon 33 add 33 back 33 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 323 327 browse 33 cd 33 cmd 33 complete 34 continue 34 def 34 delete 35 edit 35 etags 34 force 35 forward 35 help 35 history 35 info 35 issafe 35 kind 36 list 36 load 13 36 main 36 module 37 print 37 quit 37 reload 13 37 run 37 script 37 set 37 38 set m 17 set args 37 set prog 37 set1 37 38 show 38 show bindings 37 show breaks 38 show context 38 show imports 38 show language 38
186. 6 2 Writing generic functions ssaa ee 274 7 26 3 Generic defaults ee 275 7 26 4 More information sep a ace ni a p ee 213 ROLES ria ee bea ee A id A A A A 213 7 27 1 Nominal Representational and Phantom a 276 1 2122 Role interente s soye beac A e a E 276 7 27 3 Role annotations sose w ee ZII Concurrent and Parallel Haskell ee 278 7294 Concurrent Haskell ic a A aaa a E e a 278 7 28 2 Software Transactional Memory 278 1 28 35 Parallel Haskell 20 nor araca A A A A ole AGU ae a a 219 7 28 4 Annotating pure code for parallelism 0200000020 eee ee 279 7 28 5 Data Parallel Haskell ee 280 Sate Haskellis susure e es SOM ee ee SA ee E Ee ee a ER Ae ee 280 7 29 1 Uses of Safe Haskell ee ee 280 7 29 1 1 Strict type safety good Style ee 280 7 29 1 2 Building secure systems restricted IO Monads o e 281 7292 Sate Language 225 5 seek e tbe BH PES ea E A A Adee ee A 282 7 29 3 Safe Imports s s pa gh k he cheb ibe eg hake es Beebe whe Pe OE ee oe e 283 7 29 4 Trust and Safe Haskell Modes ee 283 7 29 4 1 Trust check fpackage trust disabled o o 283 7 29 4 2 Trust check fpackage trust enabled o 284 1294 3 Example sais ir A o id e A A ees 285 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 xvi 7 29 44 Trustworthy
187. 64 bits on a 64 bit machine Arithmetic on Int is unchecked for overflow so all operations on Int happen modulo 2 where n is the size in bits of the Int type The fromInteger function and hence also fromIntegral is a special case when converting to Int The value of fromIntegral x Int is given by taking the lower n bits of abs x multiplied by the sign of x in 2 s complement n bit arithmetic This behaviour was chosen so that for example writing Oxffffffff Int preserves the bit pattern in the resulting Int Negative literals such as 3 are specified by a careful reading of the Haskell Report as meaning Prelude negate Prelude fromInteger 3 S0 2147483648 means negate fromInteger 2147483648 Since fro mInteger takes the lower 32 bits of the representation fromInteger 2147483648 Integer computed at type Int is 2147483648 Int The negate operation then overflows but it is unchecked so negate 2147483648 Int is just 2147483648 In short one can write minBound Int as a literal with the expected meaning but that is not in general guaranteed The fromIntegral function also preserves bit patterns when converting between the sized integral types Int8 Int16 Int32 Int 64 and the unsigned Word variants see the modules Data Int and Data Word in the library documentation Unchecked float arithmetic Operations on Float and Double numbers are unchecked for overflow underflow and other sad occurrences not
188. 7 print libdir 47 show iface 46 54 show options 47 supported extensions 47 user 74 verbose ghc pkg option 74 version 47 74 2 74 RTS option 96 A RTS option 98 A lt size gt RTS option 148 151 B RTS option 103 C 46 48 Cs RTS option 94 D 86 RTS option 103 E 46 48 E option 48 F 87 RTS option 98 G RTS option 98 G RTS option 151 H 50 148 RTS option 99 L 86 RTS option 99 K RTS option 100 L 89 RTS option 138 M RTS option 100 M lt size gt RTS option 151 Nx RTS option 90 93 94 O 41 258 O option 78 O not specified 78 00 78 O1 option 78 02 option 79 Odph 79 P 134 136 RTS 96 Rghc timing 50 S 46 48 RTS option 100 S RTS option 151 T RTS option 100 U 86 V 47 74 RTS option 97 136 W option 60 Wall 61 Werror 61 Wwarn 61 XForeignFunctionInterface 288 XIncoherentInstances 201 XNPlusKPatterns 163 XNoImplicitPrelude option 169 303 XNoMonomorphismRestriction 237 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 320 327 XNoTraditionalRecordSyntax 163 XOverlappingInstances 201 XRoleAnnotations 277 XTemplateHaskell 244 XUndecidableInstances 201 XUnicodeSyntax 154 Z RTS option 104 auto all 132 c 46 48 88 RTS option 98 clear package db 70 cpp 48 86 cpp option 86 cpp Vs string gaps 87 dcmm lint 107 dcore lint
189. 7 10 2 196 327 Notice that the type for f allows the two parameters x and y to be assigned different types even though it attempts to insert each of the two values one after the other into the same collection If we re trying to model collections that contain only one type of value then this is clearly an inaccurate type Worse still the definition for g is accepted without causing a type error As a result the error in this code will not be flagged at the point where it appears Instead it will show up only when we try to use g which might even be in a different module 7 6 2 2 1 An attempt to use constructor classes Faced with the problems described above some Haskell programmers might be tempted to use something like the following version of the class declaration class Collects c wher Emp 34 0 8 AS Cds gt gt member gt gt Bool The key difference here is that we abstract over the type constructor c that is used to form the collection type c e and not over that collection type itself represented by ce in the original class declaration This avoids the immediate problems that we mentioned above empty has type Collects c gt c e which is not ambiguous The function f from the previous section has a more accurate type E Bo Collecis E gt gt gt a gt The function g from the previous section is now rejected with a type error as we would hope because the type of f does not all
190. Array The following code listing gives a few examples ACs Sea SIA 2 Seu Char ER oo MO se Vector int L eleicerntic 0 Mel vi a Mea Sica Acinic EA te 2 Text List patterns are also overloaded When the OverloadedLists extension is turned on these definitions are desugared as follows AS E toulet gt D a keyra oss cobuse gt x lt 7 2 Here we are using view pattern syntax for the translation see Section 7 3 8 7 6 5 1 The IsList class In the above desugarings the functions toList fromList and fromListN are all methods of the IsList class which is itself exported from the GHC Exts module The type class is defined as follows class IsList 1 where type Item 1 trombiest 53 item 11 I toList g3 i mesm i The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 206 327 FT ombisuN fe int gt Item 11 1 fromListN _ fromList The IsList class and its methods are intended to be used in conjunction with the OverloadedLists extension e The type function Item returns the type of items of the structure 1 e The function fromList constructs the structure 1 from the given list of Item 1 e The function fromListN takes the input list s length as a hint Its behaviour should be equivalent to fromList The hint can be used for more efficient construction of the structure 1 compared to fromList If the given hint is not equal to the input list s le
191. C will emit an error message 7 17 6 Template Haskell Quasi quotation Quasi quotation allows patterns and expressions to be written using programmer defined concrete syntax the motivation behind the extension and several examples are documented in Why It s Nice to be Quoted Quasiquoting for Haskell Proc Haskell Workshop 2007 The example below shows how to write a quasiquoter for a simple expression language Here are the salient features The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 249 327 e A quasi quote has the form quoter string The quoter must be the name of an imported quoter either qualified or unqualified it cannot be an arbitrary expression n The quoter cannot be e t d or p since those overlap with Template Haskell quotations There must be no spaces in the token quoter The quoted string can be arbitrary and may contain newlines The quoted string finishes at the first occurrence of the two character sequence Absolutely no escaping is per formed If you want to embed that character sequence in the string you must invent your own escape convention such as say using the string instead and make your quoter function interpret as One way to implement this is to compose your quoter with a pre processing pass to perform your escape conversion See the discussion in Trac for details e A quasiquote may appear in place of An expre
192. C code in the file foo o name notwithstanding This option is most often used when creating an executable file to set the filename of the executable For example ghe o prog make Main will compile the program starting with module Main and put the executable in the file prog Note on Windows if the result is an executable file the extension exe is added if the specified filename does not already have an extension Thus que ROO Om Macias will compile and link the module Main hs and put the resulting executable in foo exe not foo If you use ghe make and you don t use the o the name GHC will choose for the executable will be based on the name of the file containing the module Main Note that with GHC the Main module doesn t have to be put in file Main hs Thus both ghel make Prog and ghe make Prog hs will produce Prog or Prog exe if you are on Windows odir dir Redirects object files to directory dir For example S ghc c parse Foo hs parse Bar hs gurgle Bumble hs odir uname m The object files Foo o Bar o and Bumble o would be put into a subdirectory named after the architecture of the executing machine x86 mips etc Note that the odir option does not affect where the interface files are put use the hidir option for that In the above example they would still be put in parse Foo hi parse Bar hi and gurgle Bumble hi ohi file The interface output may be directed to another
193. C is itself compiled by GHC you can change RTS options in the compiler using the normal RTS RTS combination eg to set the maximum heap size for a compilation to 128M you would add RTS M128m RTS to the command line 4 17 1 2 Setting RTS options at compile time GHC lets you change the default RTS options for a program at compile time using the with rtsopts flag Section 4 12 6 A common use for this is to give your program a default heap and or stack size that is greater than the default For example to set H128m K64m link with with rtsopts H128m K64m The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 97 327 4 17 1 3 Setting RTS options with the GHCRTS environment variable If the rtsopts flag is set to something other than none when linking RTS options are also taken from the environment variable GHCRTS For example to set the maximum heap size to 2G for all GHC compiled programs using an sh like shell GHCRTS M2G export GHCRTS RTS options taken from the GHCRTS environment variable can be overridden by options given on the command line Tip setting something like GHCRTS M2G in your environment is a handy way to avoid Haskell programs growing beyond the real memory in your machine which is easy to do by accident and can cause the machine to slow to a crawl until the OS decides to kill the process and you hope it kills the right one 4 17 1 4 Hooks to change
194. C_type A Haskell equivalent of the C numeric type will be output It will be one of Int Word 8 16 32 64 Float Double LDouble peek struct_type field A function that peeks a field of a C struct will be output It will have the type Storable b gt Ptr a gt IO b The intention is that peek and poke can be used for implementing the operations of class Storable for a given C struct see the Foreign Storable module in the library documentation poke struct_type field Similarly for poke It will have the type Storable b gt Ptr a gt b gt IO ptr struct_type field Makes a pointer to a field struct It will have the type Ptr a gt Ptr b offset struct_type field Computes the offset in bytes of field in struct_type It will have type Int size struct_type Computes the size in bytes of struct_type It will have type Int enum type constructor value value A shortcut for multiple definitions which use const Each value is a name of a C integer constant e g enumeration value The name will be translated to Haskell by making each letter following an underscore uppercase making all the rest lowercase and removing underscores You can supply a different translation by writing hs_name c_value instead of a value in which case c_value may be an arbitrary expression The hs_name will be defined as having the specified type Its definition is the specified constructor which in fact may be an expression or
195. Cmm that is a simple C like language and compiling it to executable code The backends that GHC support are described below 4 11 1 Native code Generator fasm The default backend for GHC It is a native code generator compiling Cmm all the way to assembly code It is the fastest backend and generally produces good performance code It has the best support for compiling shared libraries Select it with the fasm flag 4 11 2 LLVM Code Generator 11vm This is an alternative backend that uses the LLVM compiler to produce executable code It generally produces code as with performance as good as the native code generator but for some cases can produce much faster code This is especially true for numeric array heavy code using packages like vector The penalty is a significant increase in compilation times Select the LLVM backend with the 11vm flag Currently only LLVM 3 5 is supported You must install and have LLVM available on your PATH for the LLVM code generator to work Specifically GHC needs to be able to call the opt and lle tools Secondly if you are running Mac OS X with LLVM 3 5 or greater then you also need the Clang c compiler compiler available on your PATH To install LLVM and Clang e Linux Use your package management tool e Mac OS X Clang is included by default on recent OS X machines when XCode is installed from 10 6 and later LLVM is not included In order to use the LLVM based code generator you should
196. Currently the IsList class is not accompanied with defaulting rules Although feasible not much thought has gone into how to specify the meaning of the default declarations like default a 7 6 5 4 Speculation about the future The current implementation of the OverloadedLists extension can be improved by handling the lists that are only populated with literals in a special way More specifically the compiler could allocate such lists statically using a compact representation and allow IsList instances to take advantage of the compact representation Equipped with this capability the Overloade dLists extension will be in a good position to subsume the OverloadedStrings extension currently as a special case string literals benefit from statically allocated compact representation 7 7 Type families Indexed type families form an extension to facilitate type level programming Type families are a generalisation of associated data types Associated Types with Class M Chakravarty G Keller S Peyton Jones and S Marlow In Proceedings of The 32nd Annual ACM SIGPLAN SIGACT Symposium on Principles of Programming Languages POPL 05 pages 1 13 ACM Press 2005 and associated type synonyms Type Associated Type Synonyms M Chakravarty G Keller and S Peyton Jones In Proceedings of The Tenth ACM SIGPLAN International Conference on Functional Programming ACM Press pages 241 253 2005 Type families themselves are d
197. E e a E 121 4 19 16 Profiling options 2 22 a a danes a ea ee a 124 4 19 17 Program coverage options o oo a 124 4 19 18 Haskell pre processor options ooo ee 125 4 19 19 C pre processor options s ssess eressero cst estr h emerso mapes nru 125 4 19 20 Code generation options s s e s seee eaaa E e e a e E E a 125 4 19 2 Linking Opuons errar 6 Bo ae A RR a SG e wR 125 4 19 22 Plugin Options cio wage e Wk Ra ee aOR GE Ba Sow eH Bho gaa AG ida amp aye 127 4 19 23 Replacing phases s s e 24644 6 mas e oe e A A A a 127 4 19 24 Forcing options to particular phases ee 128 4 19 25 Platform specific aptos 128 4 19 26 Compiler debugging options 2 2 a 129 4 19 27 Misc compiler options 2 a 131 5 Profiling 132 5 1 Cost centres and cost centre stacks 132 5 1 1 Inserting cost centres by hand 0 0 00000 ee ee 134 5 1 2 Rules for attributing costs 5 6 4 e wa Bye tse eo eee wars a ES Se ds RAS od 135 5 2 Compiler options for profiling 0 0 0 0 0000022 135 5 3 Time and allocation profiling 2 2 2 0 0 000 000 000002 ee 136 5 4 Profiling memory usage o sse cesse desi ceke druke tee dE Ea a E 136 5 4 1 RTS options for heap profiling oaoa 2 020 0 20000 0000000000004 137 5 4 2 Retainer Profiling s s es sa eaae ee e be ae ee A AA A E 138 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 ix 5 4 2 1 Hints for using retainer
198. E pragma 149 264 266 specifying your own main function 89 sql 165 stability package specification 76 stack chunk buffer size 99 chunk size 99 stack initial size 99 stack maximum size 100 StackOverflowHook 97 startup files GHCi 40 statements in GHCi 16 static options 39 45 Static pointers 258 strict constructor fields 83 string gaps vs cpp 87 structure command line 45 suffixes file 46 suppression 106 T tabs warning 64 Template Haskell 177 temporary files keeping 53 redirecting 53 ThreadScope 102 ticky ticky profiling 103 ticky ticky profiling 147 time profile 136 TMPDIR environment variable 53 tracing 102 trust 283 trust check 283 284 trusted package specification 77 trustworthy 285 Type default 22 type signatures missing 63 64 U Unboxed types Glasgow extension 153 unfolding controlling 83 unicode 50 UNPACK 267 unregisterised compilation 84 unused binds warning 65 unused do binding warning 65 unused imports warning 65 unused matches warning 65 using GHC 44 UTF 8 50 utilities Haskell 305 Vv verbosity options 49 version package specification 76 version of ghc 2 W WARNING 260 warnings 60 61 windres 91 Y Yacc for Haskell 305
199. E pragma for a function has a number of other effects e While GHC is keen to inline the function it does not do so blindly For example if you write map key_function xs there really isn t any point in inlining key_function to get map Xx gt body xs In general GHC only inlines the function if there is some reason no matter how slight to suppose that it is useful to do so e Moreover GHC will only inline the function if it is fully applied where fully applied means applied to as many arguments as appear syntactically on the LHS of the function definition For example Gomjoll 2 lo gt a gt lo gt a gt INLINE compl compi ae ty Wx S ie ej xe COMO CME la gt gt la gt lo gt a gt e INLINE comp2 COMPLE ok OS The two functions comp1 and comp2 have the same semantics but comp1 will be inlined when applied to two arguments while comp2 requires three This might make a big difference if you say MAS MOE OM AO E mes which will optimise better than the corresponding use of comp e It is useful for GHC to optimise the definition of an INLINE function f just like any other non INLINE function in case the non inlined version of f is ultimately called But we don t want to inline the optimised version of a major reason for INLINE pragmas is to expose functions in s RHS that have rewrite rules and it s no good if those functions
200. Furthermore testing the exception state is not reliable because a context switch may change it If you need to modify or test the floating point state and use threads then you must use bound threads Control Concurrent forkOS because a bound thread has its own OS thread and OS threads do save and restore the floating point state It is safe to modify the floating point unit state temporarily during a foreign call because foreign calls are never pre empted by GHC The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 296 327 Chapter 9 Extending and using GHC as a Library GHC exposes its internal APIs to users through the built in ghc package It allows you to write programs that leverage GHC s entire compilation driver in order to analyze or compile Haskell code programmatically Furthermore GHC gives users the ability to load compiler plugins during compilation modules which are allowed to view and change GHC s internal intermediate representation Core Plugins are suitable for things like experimental optimizations or analysis and offer a lower barrier of entry to compiler development for many common cases Furthermore GHC offers a lightweight annotation mechanism that you can use to annotate your source code with metadata which you can later inspect with either the compiler API or a compiler plugin 9 1 Source annotations Annotations are small pragmas that allow you to attach data to identifi
201. GHC will normally write interface files automatically but this flag is useful with fno code which normally suppresses generation of interface files This is useful if you want to type check over multiple runs of GHC without compiling dependencies fobject code Generate object code This is the default outside of GHCi and can be used with GHCi to cause object code to be generated in preference to bytecode fbyte code Generate byte code instead of object code This is the default in GHCi Byte code can currently only be used in the interactive interpreter not saved to disk This option is only useful for reversing the effect of fobject code fPIC Generate position independent code code that can be put into shared libraries This currently works on Linux x86 and x86 64 On Windows position independent code is never used so the flag is a no op on that platform dynamic When generating code assume that entities imported from a different package will reside in a different shared library or binary Note that using this option when linking causes GHC to link against shared libraries 4 12 6 Options affecting linking GHC has to link your code with various libraries possibly including user supplied GHC supplied and system supplied 1m math library for example 11ib Link in the 1ib library On Unix systems this will be in a file called 1ib1ib a or 1ib1ib so which resides somewhere on the library directories path Becaus
202. Glasgow Haskell Compilation System User s Guide Version 7 10 2 316 327 e Whenever you give a function instance or class a Bits t constraint also give ita Num t constraint and e Always define the bit testBit and popCount methods in Bits instances Extra instances The following extra instances are defined LMS ane Sm PUNET gt E instance Monad gt r instance Functor a instance Functor Either a instance Monad Either e Multiply defined array elements not checked This code fragment should elicit a fatal error but it does not media roine eres UL Mya yy GHC s implementation of array takes the value of an array slot from the last index value pair in the list and does no checking for duplicates The reason for this is efficiency pure and simple 13 1 1 7 In Prelude support Arbitrary sized tuples Tuples are currently limited to size 100 HOWEVER standard instances for tuples Eq Ord Boun ded Ix Read and Show are available only up to 16 tuples This limitation is easily subvertible so please ask if you get stuck on it splitAt semantics Reading integers GHC s implementation of the Read class for integral types accepts hexadecimal and octal literals the code in the Haskell 98 report doesn t So for example isa Mae OY 25 T as works in GHC A possible reason for this is that readLitChar accepts hex and octal escapes so it seems inconsistent not to do so for integ
203. Glasgow Haskell Compilation System User s Guide Version 7 10 2 176 327 7 3 26 3 Safe imports With the XSafe XTrustworthy and XUnsafe language flags GHC extends the import declaration syntax to take an optional safe keyword after the import keyword This feature is part of the Safe Haskell GHC extension For example import safe qualified Network Socket as NS would import the module Network Socket with compilation only succeeding if Network Socket can be safely imported For a description of when a import is considered safe see Section 7 29 7 3 26 4 Explicit namespaces in import export In an import or export list such as module M f where import N f the entities f and are values However with type operators Section 7 4 4 it becomes possible to declare as a type constructor In that case how would you export or import it The XExplicitNamespaces extension allows you to prefix the name of a type constructor in an import or export list with type to disambiguate this case thus module M f type where import N f type module N f type where data family at t b LaJ Rb The extension XExplicitNamespaces is implied by XTypeOperators and for some reason by XTypeFamilies In addition with XPatternSynonyms you can prefix the name of a data constructor in an import or export list with the keyword pattern to allow the import or export of a data constructor
204. HCi run The flag reference tables Section 4 19 lists the status of each flag There are a few flags that are static except that they can also be used with GHCi s set command these are listed as static set in the table The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 46 327 4 4 Meaningful file suffixes File names with meaningful suffixes e g 1hs or o cause the right thing to happen to those files hs A Haskell module lhs A literate Haskell module hspp A file created by the preprocessor hi A Haskell interface file probably compiler generated hc Intermediate C file produced by the Haskell compiler c AC file not produced by the Haskell compiler 11 An llvm intermediate language source file usually produced by the compiler be An llvm intermediate language bitcode file usually produced by the compiler s An assembly language source file usually produced by the compiler 0 An object file produced by an assembler Files with other suffixes or without suffixes are passed straight to the linker 4 5 Modes of operation GHC s behaviour is firstly controlled by a mode flag Only one of these flags may be given but it does not necessarily need to be the first option on the command line If no mode flag is present then GHC will enter make mode Section 4 5 1 1f there are any Haskell source files given on the command line o
205. IO where return UnsafeRIO return UnsafeRIO m gt gt k UnsafeRIO m gt gt runRIO k Returns True iff access is allowed to file name patnok Bee au ALO MB ool pathOK fil Implement some policy based on file name rioReadFile FilePath gt RIO String rioReadFile file UnsafeRIO do ok lt pathOK file if ok then readFile fil lse return TLOM etcem BS jake encla gt Sicilia gt RIO rioWriteFile file contents UnsafeRIO do ok lt pathOK file if ok then writeFile file contents else return We compile Danger using the new Safe Haskell XSafe flag LANGUAGE Safe module Danger runMe where runMe RIO runMe Before going into the Safe Haskell details lets point out some of the reasons this design would fail without Safe Haskell e The design attempts to restrict the operations that Danger can perform by using types specifically the RIO type wrapper around IO The author of Danger can subvert this though by simply writing arbitrary TO actions and using unsafePerform10 IO a gt ato execute them as pure functions e The design also relies on the Danger module not being able to access the UnsafeRIO constructor Unfortunately Template Haskell can be used to subvert module boundaries and so could be used to gain access to this constructor e There is no way to place restrictions on the modules that the untrusted Danger module can import This gives
206. If you have trouble because of running out of space in tmp or wherever your installation thinks temporary files should go you may use the tmpdir lt dir gt option to specify an alternate directory For example tmpdir says to put temporary files in the current working directory Alternatively use your TMPDIR environment variable Set it to the name of the directory where temporary files should be put GCC and other programs will honour the TMPDIR variable as well Even better idea Set the DEFAULT_TMPDIR make variable when building GHC and never worry about TMPDIR again see the build documentation 4 7 7 Other options related to interface files ddump hi Dumps the new interface to standard output ddump hi diffs 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 ddump hi diffs option will make GHC report the differences between the old and new hi files The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 54 327 ddump minimal imports Dump to the file M imports where M is the name of the module being compiled a mini mal set of import declarations The directory where the imports files are created can be controlled via the dumpdir option You can safely replace all the import declarations in M hs with those found in its respe
207. Int not x Int gt Int Hence f 9 returns result 9 If you add a type signature for y then y will get type x Int gt Int so the occurrence of y in the body of the 1et will see the inner binding of x so 9 will return 14 7 13 4 5 Special implicit parameters GHC treats implicit parameters of type GHC Stack CallStack specially by resolving them to the current location in the program Consider E 88 Stig SO WAR AO CAE AS AC GHC will automatically resolve 1oc to its source location If another implicit parameter with type Cal1Stack is in scope GHC will append the two locations creating an explicit call stack For example Roark 26 Callsracik gt iSieiealiave ie i inion ROCk 8k Caelllilsicevels The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 230 327 will produce the location of stk followed by s call site Note that the name of the implicit parameter does not matter we used loc above GHC will solve any implicit parameter with the right type The name does however matter when pushing new locations onto existing stacks Consider E 88 POSTE gs Callstacis gt SLINE ES O WR SAO AS ES aca When we call f the stack will include the use of 10c but not the call to f in this case the names must match CallStack is kept abstract but GHC provides a function dere ita O MS ta ci MSP OO COS to access the individual call sites in the stack The St
208. L for this package The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 78 327 4 9 10 Package environments A package environment is a file that tells ghc precisely which packages should be visible It contains package IDs one per line package_id_1 package_id_2 package_id_n If a package environment is found it is equivalent to passing these command line arguments to ghc hide all packages package id package_id_1 package id package_id_2 package id package_id_n In order ghc will look for the package environment in the following locations e File file if you pass the option package env file e File SHOME ghc arch os version environments name if you pass the option package env name e File file ifthe environment variable GHC_ ENVIRONMENT is set to file File SHOME ghc arch os version environments name if the environment variable GHC_ENVIRONMENT is set to name e File ghc environment if it exists File SHOME ghc arch os version environments default if it exists Package environments can be modified by further command line arguments for example if you specify package foo on the command line then package foo will be visible even if it s not listed in the currently active package environment 4 10 Optimisation code improvement The O options specify convenient packages of optimisation flags the fx options described later on specify individu
209. LUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED IN NO EVENT SHALL THE UNIVERSITY COURT OF THE UNIVERSITY OF GLASGOW OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT INDIRECT INCIDENTAL SPECIAL EXEMPLARY OR CONSEQUENTIAL DAMAGES INCLUDING BUT NOT LIMITED TO PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES LOSS OF USE DATA OR PROFITS OR BUSINESS INTERRUPTION HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY WHETHER IN CONTRACT STRICT LIABILITY OR TORT INCLUDING NEGLIGENCE OR OTHERWISE ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 1 327 Chapter 1 Introduction to GHC This is a guide to using the Glasgow Haskell Compiler GHC an interactive and batch compilation system for the Haskell 98 language GHC has two main components an interactive Haskell interpreter also known as GHCi described in Chapter 2 and a batch compiler described throughout Chapter 4 In fact GHC consists of a single program which is just run with different options to provide either the interactive or the batch system The batch compiler can be used alongside GHCi compiled modules can be loaded into an interactive session and used in the same way as interpreted code and in fact when using GHCi most of the library code will be pre compiled This means you g
210. NO Cihiahe Rather than generating code to call according to the platform s ABI we instead call using the C API defined in the header header h Thus f can be called even if it may be defined as a CPP define rather than a proper function When using capi it is also possible to import values rather than functions For example LOGIN amore Cejoa oi pln Welle jou Cit gs CDaisile will work regardless of whether pi is defined as const double pi 3 14 or with The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 290 327 define pi 3 14 In order to tell GHC the C type that a Haskell type corresponds to when it is used with the CAPI a CTYPE pragma can be used on the type definition The header which defines the type can optionally also be specified The syntax looks like data newtype VEEN SEA in Wusecomels EY 5 1 YPE Secondo aat E i i E 8 1 6 hs_thread_done void hs_thread_done void GHC allocates a small amount of thread local memory when a thread calls a Haskell function via a foreign export This memory is not normally freed until hs_exit the memory is cached so that subsequent calls into Haskell are fast However 1f your application is long running and repeatedly creates new threads that call into Haskell you probably want to arrange that this memory is freed in those threads that have finished calling Haskell functions To do this call hs
211. PIC and shared 4 13 3 Shared libraries that export a C API Building Haskell code into a shared library is a good way to include Haskell code in a larger mixed language project While with static linking 1t is recommended to use GHC to perform the final link step with shared libraries a Haskell library can be treated just like any other shared library The linking can be done using the normal system C compiler or linker It is possible to load shared libraries generated by GHC in other programs not written in Haskell so they are suitable for using as plugins Of course to construct a plugin you will have to use the FFI to export C functions and follow the rules about initialising the RTS See Section 8 2 1 2 In particular you will probably want to export a C function from your shared library to initialise the plugin before any Haskell functions are called To build Haskell modules that export a C API into a shared library use the dynamic fPIC and shared flags ghc make dynamic shared fPIC Foo hs o libfoo so As before the dynamic flag specifies that this library links against the shared library versions of the rts and base package The fPIC flag is required for all code that will end up in a shared library The shared flag specifies to make a shared library rather than a program To make this clearer we can break this down into separate compilation and link steps gia aynan ei ETOR 8 olas Sine oynani ei emazco 109 0 9 Listo
212. RE OR ee ee Re wR ER HOO a 206 765 3 Defaulling a 4 56425 44082 44 et 4040 bE ed eaA ee eee eA eee eee 207 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 xii 7 6 5 4 Speculation about the future 2 ee 207 Tel Type Tanulles 4 2 96 es Bae ie a eG Re eee Ree EES eee oe 207 4 1 1 Datatamilies s sa seco bed be aE RS ee ee eR Se ee oe 207 7 7 1 1 Data family declarations 2 2 ee 208 7 7 1 2 Data instance declarations lt o eves ee 208 7 7 1 3 Overlap of data instances oaao ee 209 1 1 2 Synonym famili s 2 ee s ce cocer estie a ee a ee ee ea ee 209 7 1 2 1 Type family declarations a 209 7 7 2 2 Type instance declarations csecsenc ee 210 712 3 Closedtyp families n 3 ex oye 2 Ph we BES ee ES AA i 210 7 7 2 4 Type family examples 00 000000202 ee eee eee 210 7 7 2 5 Compatibility and apartness of type family equations 00 211 7 1 2 6 Decidability of type synonym instances e 212 7 7 3 Associated data and type families aa 0 200002 2p ee 212 7 7 3 1 Associatedinstances sos cerua ee 212 7 1 3 2 Associated type synonym defaults 2 2 0 0 2 0 0000000000000 213 7 1 3 3 Scoping of class parameters 214 7 1 3 4 Instance contexts and associated type and data instances o o 214 7 74 Importand erp 214 TIAL Examples suse ee eta ee draa ee eee bbw be ee ee a ed 215 TAZAS o
213. REC TARTS AO OU Gt a gt gt Meno az Here Lookup is declared INLINABLE but it cannot be specialised for type T at its definition site because that type does not exist yet Instead a client module can define T and then specialise Lookup at that type Moreover every module that imports Client or imports a module that imports Client transitively will see and make use of the specialised version of Lookup You don t need to put a SPECIALIZE pragma in every module Moreover you often don t even need the SPECIALIZE pragma in the first place When compiling a module M GHC s optimiser with O automatically considers each top level overloaded function declared in M and specialises it for the different types at which it is called in M The optimiser also considers each imported INLINABLE overloaded function and specialises it for the different types at which it is called in M So in our example it would be enough for lookup to be called at type T module Client wher import Map lookup Glace ail ELO Sn AO cal ge i a gt Menos a findT1 m lookup m Tl A cell looks ae cyose T However sometimes there are no such calls in which case the pragma can be useful 7 22 9 3 Obsolete SPECIALIZE syntax Note In earlier versions of GHC it was possible to provide your own specialised function for a given type SPECIALIZE hammeredLookup Int value
214. Requirements 0 0 000002 ee eee eee 285 7294 5 Package Trust s nq 5 sees kage nee eee Gade eee lees bebe ook be Me bw 285 7 29 5 Sate Haskell Inference soes nor Macks Sa ASR RR ee a ee A Pe Ee wo 285 7 29 6 Safe Haskell Flag Summary 286 1 29 17 Sate Compilation s 4 5 4 36 Bye e o a AA eyed AB Se chet de e 287 8 Foreign function interface FFI 288 8 1 GHC extensions to the FFI Addendum 2 2 20 0 20 0 020000 000000000000 0000 288 8 1 1 Unboxed types 4 oe ha eee ER a a eae ES ee ee ae owas a 288 8 1 2 Newtype wrapping of the IO mona 288 1 3 Primitive 1MpOrts ssec epea E A RA A aa e 289 8 1 4 Interruptible foreign calls ee 289 8 1 5 The CAPI calling convention lt s 2 2 0 0 000000 e E E E E 289 8 1 6 hs thread donas rae 5 625 68 ada ae da a ld 290 82 Using the FFL with GHC cocos deb ERA Aiuti tkk AA Oe e ee 290 8 2 1 Using foreign export and foreign import ccall wrapper with GHC 290 9 2 1 1 Using yourownmain 60 5 ae e bbe ae Ya See a 291 8 2 1 2 Making a Haskell library that can be called from foreign code 292 2 2 Using header les ae tad e e A AAA AAA i 4 293 823 Memory Allocations es ega pe rar a As E 293 8 2 4 Multi threading and the FFI ee 294 8 2 4 1 Foreign imports and multi threading e 294 8 2 4 2 The relationship between Haskell threads and OS threads o o 294 8 2 4 3 F
215. Section 7 27 Then the derived instance is of form declaration is sane iil oiea EAS wil 5 wis The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 192 327 As an example which does not work consider newtype NonMonad m s NonMonad State s m s deriving Monad Here we cannot derive the instance instance Monad State s m gt Monad NonMonad m because the type variable s occursin State s m and so cannot be eta converted away It is a good thing that this deriving clause is rejected because NonMonad mis not in fact a monad for the same reason Try defining gt gt with the correct type you won t be able to Notice also that the order of class parameters becomes important since we can only derive instances for the last one If the StateMonad class above were instead defined as class StateMonad m s m gt s where then we would not have been able to derive an instance for the Parser type above We hypothesise that multi parameter classes usually have one main parameter for which deriving new instances is most interesting Lastly all of this applies only for classes other than Read Show Typeable and Data for which the built in derivation applies section 4 3 3 of the Haskell Report For the standard classes Eq Ord Ix and Bounded it is immaterial whether the standard method is used or the one described here 7 5 6 Deriving any other class With XDeriveAnyCl
216. Set fal e type declarations EOS I GE 88 ss S 2 dE lime e class declarations elass EQ E gt C 2 28 gt 3 asias e forall s in type signatures O ES ISA RO La The parentheses are required Some of the spaces are required too to separate the lexemes If you write gt x you will get a parse error because gt x is a single lexeme in Haskell As part of the same extension you can put kind annotations in types as well Thus i 8 8 bate 88 3 gt Joe JE O A gi gt e g The syntax is aye 232 e cenas Yas Kino E The parentheses are required The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 231 327 7 13 6 Arbitrary rank polymorphism GHC s type system supports arbitrary rank explicit universal quantification in types For example all the following types are legal cl gg exa a los E gt lo gt ai UE O RI a dy Orti ap Be Io gt a gt lo a if ge forall a aca gt Int gt Ime GA 88 rore as me a leal gt a gt Bel gt Ime gt ilu Es 1 forall a a za Lat Bool gt BOGI r go ae gt ToOrall a a gt E Here 1 and g1 are rank 1 types and can be written in standard Haskell e g f1 a gt b gt a The forall makes explicit the universal quantification that is implicitly added by Haskell The functions 2 and g2 have rank 2 types the fora11 is on the left of a function a
217. Stolen by XImplicitParams l lel pl dl t1 Il el varid varid Stolen by XTemplateHaskell varid Stolen by XQuasiQuotes varid char string integer float float Stolen by XMagicHash Stolen by XUnboxedTuples varid varid Stolen by XBangPatterns pattern Stolen by XPatternSynonyms 7 4 Extensions to data types and type synonyms 7 4 1 Data types with no constructors With the XEmptyDataDecls flag or equivalent LANGUAGE pragma GHC lets you declare a data type with no construc tors For example data S 38 Y data T a 1D gg 8 gt 8 Syntactically the declaration lacks the constrs part The type can be parameterised over types of any kind but if the kind is not x then an explicit kind annotation must be used see Section 7 13 5 Such data types have only one value namely bottom Nevertheless they can be useful when defining phantom types 7 4 2 Data type contexts Haskell allows datatypes to be given contexts e g data Eq a gt Set a NilSet ConsSet a Set a give constructors with types Naiset Set a Sons gt Sta ae Seta Seta This is widely considered a misfeature and is going to be removed from the language In GHC it is controlled by the deprecated extension DatatypeContexts 7 4 3 Infix type constructors classes and type variables GHC allows type constructors classes and type variables to be operators and to be
218. String Note that GHC must be sure that a cannot unify with Int or Bool in that last case if a programmer specifies just F a in their code GHC will not be able to simplify the type After all a might later be instantiated with Int A closed type family s equations have the same restrictions as the equations for an open type family instances 7 7 2 4 Type family examples Here are some examples of admissible and illegal type instances type family F a x type instance F Int Int OK type instance F String Char Oe type instance F F a a WRONG type parameter mentions a type family type instance F forall a a b b WRONG a forall type appears in a type parameter type instance F Float forall a a WRONG right hand side may not be a forall type type family H a where OK Ea Hye HBO 4B 0018 Jak Gl String type instance H Char Char WRONG cannot have instances of closed family Tyas Temuily O Ello Be wy SS GS type instance G Int a WRONG must be two type parameters type instance G Int Char Float Double WRONG must be two type parameters The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 211 327 7 7 2 5 Compatibility and apartness of type family equations There must be some restrictions on the equations of type families lest we define an ambiguous rewrite system So equations of open type families are restricted to be compatible
219. T e The form T ci fj Where Tis a data family names T and the specified constructors ci and fields fj as usual The constructors and field names must belong to some data instance of T but are not required to belong to the same instance e The form C where C is a class names the class C and all its methods and associated types e The form C mi type Tj where C is a class names the class C and the specified methods mi and associated types Tj The types need a keyword type to distinguish them from data constructors The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 215 327 7 7 4 1 Examples Recall our running GMapKey class example class GMapKey k where Clana EMEnO le 88 te gt 5 NS MAGMA lookup GMap k v gt k gt Maybe v empty GMap k v instance GMapKey a GMapKey b gt GMapKey Either a b where data GMap Either a b v GMapEither GMap a v GMap b v method declarations Here are some export lists and their meaning e module GMap GMapKey Exports just the class name e module GMap GMapKey Exports the class the associated type GMap and the member functions empty lookup and insert The data constructors of GMap in this case GMapEither are not exported e module GMap GMapKey type GMap empty lookup insert Same as the previous item Note the type keyword e module GMap GMapKey
220. TS Is this program linked against the GHC RTS always YES version The version of GHC used to compile this program way The variant way of the runtime The most common values are rt s_v vanilla rt s_thr threaded runtime i e linked using the threaded option and rt s_p profiling runtime i e linked using the prof option Other variants include debug linked using debug and dyn the RTS is linked in dynamically i e a shared library rather than statically linked into the executable itself These can be combined e g you might have rt s_thr_debug_p Target platform Target architecture Target OS Target vendor These are the platform the program is compiled to run on Build platform Build architecture Build OS Build vendor These are the platform where the program was built on That is the target platform of GHC itself Ordinarily this is identical to the target platform It could potentially be different if cross compiling Host platform Host architecture Host OS Host vendor These are the platform where GHC itself was com piled Again this would normally be identical to the build and target platforms Word size Either 32 or 64 reflecting the word size of the target platform The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 105 327 Compiler unregistered Was this program compiled with an unregistered version of GHC Le a version of GHC that has no plat
221. The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 COLLABORATORS TITLE The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 ACTION NAME DATE SIGNATURE WRITTEN BY The GHC Team July 22 2015 REVISION HISTORY NUMBER DATE DESCRIPTION NAME The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 iii Contents 1 Introduction to GHC 1 1 1 Obtaining GHC oc es e a eS ROS Roe BS ee eh a ae la 1 1 2 Meta information Web sites mailing lists etc o ee 1 1 3 Reporting b ssin GHG eri aros Bee he Re a aA ROE ROS Bae ae kG wa god a ee 2 1 4 GHC version numbering policy 2 2 0 000 2 2 1 5 Release notes for version 7 10 1 eoo e soccer 00000002 2 E E 3 TS Shits sea Bs et TR 3 15 2 Full details 2 v0 240s eee de eee ee e eE ae ee a ee ee a a 3 W521 DLaneuage oras Bae SaaS ERG eR ES Bare Maa AS eal ged amp ak 3 15 2 2 Compiler s 6244445 beac ee tie beaw nob e pO eee ee eae ee e 4 E323 GMC 2456 AA SAS SS 5 1 5 2 4 Template Haskell sp 2 45 2244 Pid Re SRK a 3 15 25 R ntimesyst m s se decies sea ad a ee a ee 6 1 5 2 6 BuldsysteM sneis aia e ao o ar a od amp oS 6 1 5 2 7 Package SYSteM 22
222. Tuned By Someone Else You might be able to write a better quicksort than the one in Data List but it will take you much longer than typing import Data List Please report any overly slow GHC compiled programs Since GHC doesn t have any credible competition in the performance department these days it s hard to say what overly slow means so just use your judgement Of course if a GHC compiled program runs slower than the same program compiled with NHC or Hugs then it s definitely a bug Optimise using O or 02 This is the most basic way to make your program go faster Compilation time will be slower especially with 02 At present O2 is nearly indistinguishable from 0O Compile via LLVM The LLVM code generator can sometimes do a far better job at producing fast code than the native code generator This is not universal and depends on the code Numeric heavy code seems to show the best improvement when compiled via LLVM You can also experiment with passing specific flags to LLVM with the opt lo and optic flags Be careful though as setting these flags stops GHC from setting its usual flags for the LLVM optimiser and compiler Overloaded functions are not your friend Haskell s overloading using type classes is elegant neat etc etc but it is death to performance if left to linger in an inner loop How can you squash it Give explicit type signatures Signatures are the basic trick putting them on exported top le
223. Two type patterns are compatible if 1 all corresponding types in the patterns are apart or 2 the two patterns unify producing a substitution and the right hand sides are equal under that substitution Two types are considered apart if for all possible substitutions the types cannot reduce to a common reduct The first clause of compatible is the more straightforward one It says that the patterns of two distinct type family instances cannot overlap For example the following is disallowed type instance F Int Bool type instance F Int Char The second clause is a little more interesting It says that two overlapping type family instances are allowed if the right hand sides coincide in the region of overlap Some examples help here type instance F a Int a type instance F Int b b overlap permitted cs imstemas E Ey We lal type instance G Char a a ILLEGAL overlap as Char Int Note that this compatibility condition is independent of whether the type family is associated or not and it is not only a matter of consistency but one of type safety The definition for compatible uses a notion of apart whose definition in turn relies on type family reduction This condition of apartness as stated is impossible to check so we use this conservative approximation two types are considered to be apart when the two types cannot be unified even by a potentially infinite unifier Allowing t
224. Windows ghc make XTemplateHaskell main hs o main exe Run main exe and here is your output main Hello 7 17 5 Using Template Haskell with Profiling Template Haskell relies on GHC s built in bytecode compiler and interpreter to run the splice expressions The bytecode inter preter runs the compiled expression on top of the same runtime on which GHC itself is running this means that the compiled code referred to by the interpreted expression must be compatible with this runtime and in particular this means that object code that is compiled for profiling cannot be loaded and used by a splice expression because profiled object code is only compatible with the profiling version of the runtime This causes difficulties if you have a multi module program containing Template Haskell code and you need to compile it for profiling because GHC cannot load the profiled object code and use it when executing the splices Fortunately GHC provides a workaround The basic idea is to compile the program twice 1 Compile the program or library first the normal way without prof 2 Then compile it again with prof and additionally use osuf p_o to name the object files differently you can choose any suffix that isn t the normal object suffix here GHC will automatically load the object files built in the first step when executing splice expressions If you omit the osuf flag when building with prof and Template Haskell is used GH
225. You can omit any combination of arguments to the tuple as in the following A CN t337 which translates to Ya bed gt a Y la Love cl 1887 If you have unboxed tuples enabled tuple sections will also be available for them like so True Because there is no unboxed unit tuple the following expression continues to stand for the unboxed singleton tuple data constructor 7 3 19 Lambda case The XLambdaCase flag enables expressions of the form ease pl gt el pN gt eN which is equivalent to freshNam gt cases r reshiNamcu or Jal gt Glp mney JAN gt EN Note that case starts a layout so you can write Xcase fl gt Sil ONE FEN The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 171 327 7 3 20 Empty case alternatives The XEmptyCase flag enables case expressions or lambda case expressions that have no alternatives thus Case e of No alternatives or case XLambdaCase is also required This can be useful when you know that the expression being scrutinised has no non bottom values For example data Void E 8 Voro gt Tie f x case x of With dependently typed features it is more useful see Trac For example consider these two candidate definitions of absurd data a b where ROGI 28 223 a closjituas s Drue keg Talee gt El absurd x error absurd A absurd x case
226. _thread_done from the thread whose memory you want to free Calling hs_thread_done is entirely optional You can call it as often or as little as you like It is safe to call it from a thread that has never called any Haskell functions or one that never will If you forget to call it the worst that can happen is that some memory remains allocated until hs_exit is called If you call it too often the worst that can happen is that the next call to a Haskell function incurs some extra overhead 8 2 Using the FFI with GHC The following sections also give some hints and tips on the use of the foreign function interface in GHC 8 2 1 Using foreign export and foreign import ccall wrapper with GHC When GHC compiles a module say M hs which uses foreign export or foreign import wrapper it generates two additional files M_stub c and M_stub h GHC will automatically compile M_stub c to generate M_stub o at the same time For a plain foreign export the file M_stub h contains a C prototype for the foreign exported function and M_stub c contains its definition For example if we compile the following module module Foo where Orere qUe CEILI oo 83 tmr gt 10 ile 199 28 low gt 10 Ida foo n return length f n i 88 ae gt Milos 2 03 11 AN LO Then Foo_stub h will contain something like this include HsFFI h extern HsInt foo HsInt a0 and Foo_stub c contains the compiler generated definition of f
227. a ntification dynamic XNoExplicitForAll XExplicitNamespa ces Enable using the keyword type to specify the namespace of entries in imports and exports Section 7 3 26 4 Implied by XTypeOperators and XTypeFamilies dynamic XNoExplicitNamesp aces XExtendedDefaultR ules Use GHCi s extended default rules in a normal module dynamic XNoExtendedDefaul tRules XFlexibleContexts Enable flexible contexts Implied by XImplicitParams dynamic XNoFlexibleCont xts XFlexiblelnstances Enable flexible instances Implies XTypeSynonym Instances Implied by XImplicitParams dynamic XNoFlexiblelnstan ces XForeignFunctionl nterface Enable foreign function interface dynamic XNoForeignFunctio ninterface XFunctionalDepend encies Enable functional dependencies Implies XMultiParamTypeCla sses dynamic XNoFunctionalDepe ndencies XGADTs Enable generalised algebraic data types Implies XGADTSyntax and XMonoLocalBinds dynamic XNOGADTs XGADTSyntax Enable generalised algebraic data type syntax dynamic XNoGADTSyntax XGeneralizedNewty peDeriving Enable newtype deriving dynamic XNoGeneralizedNew typeDeriving XGenerics Deprecated does nothing No longer enables generic classes See also GHC s support for generic programming dynamic
228. a COLOR k a xS oac SUM Soon RUS role ol forall k w Ej oldi k a wild 5 0g k z a Since xs is used twice GHC does not fire the foldr build rule Rightly so because it might take a lot of work to compute xs which would be duplicated if the rule fired Sometimes however this approach is over cautious and we do want the rule to fire even though doing so would duplicate redex There is no way that GHC can work out when this is a good idea so we provide the CONLIKE pragma to declare it thus INLINE CONLIKE 1 f x blah CONLIKE is a modifier to an INLINE or NOINLINE pragma It specifies that an application of f to one argument in general the number of arguments to the left of the sign should be considered cheap enough to duplicate if such a duplication would make rule fire The name CONLIKE is short for constructor like because constructors certainly have such a property The CONLIKE pragma is a modifier to INLINE NOINLINE because it really only makes sense to match on the LHS of a rule if you are sure that f is not going to be inlined before the rule has a chance to fire The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 271 327 7 23 5 List fusion The RULES mechanism is used to implement fusion deforestation of common list functions If a good consumer consumes an intermediate list constructed by a good producer the intermediate list should be elimi
229. a file with the t ix suffix in this case Recip tix which contains the coverage data for this run of the program The program may be run multiple times e g with different test data and the coverage data from the separate runs is accumulated in the t ix file To reset the coverage data and start again just remove the t ix file Having run the program we can generate a textual summary of coverage hpc report Recip 80 expressions used 81 101 12 boolean coverage 1 8 14 guards 1 7 3 always True 1 always False 2 unevaluated 0 if conditions 0 1 1 always False 100 qualifiers 0 0 55 alternatives used 5 9 100 local declarations used 9 9 100 top level declarations used 5 5 We can also generate a marked up version of the source hpc markup Recip writing Recip hs html This generates one file per Haskell module and 4 index files hpc_index html hpc_index_alt html hpc_index_exp html hpc_index_fun t 5 7 2 Options for instrumenting code for coverage fhpc Enable code coverage for the current module or modules being compiled Modules compiled with this option can be freely mixed with modules compiled without it indeed most libraries will typically be compiled without fhpc When the program is run coverage data will only be generated for those modules that were compiled with fhpc and the hpc tool will only show information about those modules 5 7 3 The hpc toolkit The hpc command has s
230. a main function in module Main When testing it is often convenient to change which function is the main one and the main is flag allows you to do so The thing can be one of e A lower case identifier foo GHC assumes that the main function is Main foo A module name A GHC assumes that the main function is A main e A qualified name A foo GHC assumes that the main function is A foo Strictly speaking main is is not a link phase flag at all it has no effect on the link step The flag must be specified when compiling the module containing the specified main function e g module A in the latter two items above It has no effect for other modules and hence can safely be given to ghc make However if all the modules are otherwise up to date you may need to force recompilation both of the module where the new main is and of the module where the main function used to be ghc is not clever enough to figure out that they both need recompiling You can force recompilation by removing the object file or by using the f force recomp flag no hs main 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 compiler when linking use no hs main See also Section 8 2 1 1 Notice that since the command line passed to the linker is rather involved you probably want to use ghc to do the
231. a type signature such as reliance on the Riemann hypothesis or add some globally configurable settings in a program For example class RiemannHypothesis where ISSUE Bk s a Deterministic version of the Miller test correctness depends on the generalized Riemann hypothesis isPrime RiemannHypothesis gt Integer gt Bool isPrime n assumeRH The type signature of isPrime informs users that its correctness depends on an unproven conjecture If the function is used the user has to acknowledge the dependence with instance RiemannHypothesis where assumeRH id 7 6 2 Functional dependencies Functional dependencies are implemented as described by Mark Jones in Type Classes with Functional Dependencies Mark P Jones In Proceedings of the 9th European Symposium on Programming ESOP 2000 Berlin Germany March 2000 Springer Verlag LNCS 1782 Functional dependencies are introduced by a vertical bar in the syntax of a class declaration e g class Monad m gt MonadState s m m gt s where class Foo a b e a b gt c where There should be more documentation but there isn t yet Yell if you need it 7 6 2 1 Rules for functional dependencies In a class declaration all of the class type variables must be reachable in the sense mentioned in Section 7 13 2 from the free variables of each method type For example class Coll s a where empty 83 S IMsees 2S S gt a gt 5 is not OK
232. ace GHCi support 12 formatting dumps 106 framework dirs package specification 77 frameworks package specification 77 fromInteger 317 fromIntegral 317 G garbage collection compacting 98 garbage collector options 98 generations number of 98 getArgs 37 getProgName 37 ghc backends 84 ghc code generators 84 GHC vs the Haskell standards 314 GHC using 44 GHC_PACKAGE_PATH 70 GHCGi 12 ghci 46 GHCRTS 97 Glasgow Haskell mailing lists 1 Glasgow Parallel Haskell 279 group 165 H haddock html package specification 77 haddock interfaces package specification 77 Happy 305 happy parser generator 305 Haskell Program Coverage 143 Haskell standards vs GHC 314 heap profiles 140 heap size factor 98 heap size maximum 100 heap size suggested 99 heap space using less 151 heap minimum free 100 help options 46 hidden modules package specification 76 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 325 327 homepage package specification 76 hooks RTS 97 hp2ps 140 hp2ps program 140 hpc 143 hs boot files 54 hs libraries package specification 77 hsc2hs 305 Hugs 12 hugs options package specification 77 I id package specification 76 idle GC 99 implicit context quantification warning 65 implicit parameters 177 implicit prelude warning 62 import lists missing 63 import dirs package specification 77 importing hi boot files
233. ace a ROS BAe a Baga e ae 2i 2 4 6 The main and run commands oaaae 0 0 0 0 ee ee 21 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 v 24AT The TE Yanable s scm bs ie oe a a be a g e a wo E 22 2 4 8 Type defaulting in GHC 2 2 00 000000 me aa a 22 2 4 9 Using a custom interactive printing function ooo ee 23 23 The GHC Debugger cin a acey e A AR ARA bee A a 24 2 5 1 Breakpoints and inspecting Varlables e 24 20 L Setting breakpomts gon 6 eae ata EE 26 2 5 1 2 Listing and deleting breakpoints e 27 2 5 2 Single steppiNg s opor e e RR e e a 2 233 Nested break poms xe tt a Cav di ta As A oa 28 2 34 The result variables hos isis e a id a e a e e a 28 2 5 5 Tracingand history secs s ee RR RR RR ER ee a ewe a 28 25 6 Debugging exceptions irec poeti os Sy Sai be oH eE ad wag MNS Seeds AA s 30 2 5 7 Example inspecting functions oaoa 30 25 8 Limitations lt s sae A A EA E ee E 31 236 InvoKk Me GHC 22 2 4 rra A Se A AAA AS a eee ou 32 26 1 Packages cpm a o A E 32 2 6 2 Extra branes y ly ir A A A dE ERAS ee E S 32 27 GHCi commands s e saot moso A A O AG AR a A a 33 2 8 The set and seti commands soaa 0 00 eee ee 38 28 1 lt GHCLOpuons y fs caus a AR eS ee A dE e 38 2 8 2 Setting GHC command line optionsinGHCi 2 0 0 0 00000000004 39 2 8 3 Setting options for interactiv
234. ackages on a users machine A maintainer of a package foo that uses Safe Haskell so that security conscious Haskellers can use foo now may have other users of foo who don t know or care about Safe Haskell complaining about compilation problems they are having with foobecause a package barthat foo requires isn t trusted on their machine In this sense the fpackage trust flag can be thought of as a flag to properly turn on Safe Haskell while without it it s operating in a covert fashion Having the fpackage trust flag also nicely unifies the semantics of how Safe Haskell works when used explicitly and how modules are inferred as safe The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 285 327 7 29 4 3 Example Package Wuggle LANGUAGE Safe module Buggle wher import Prelude O oo Package P LANGUAGE Trustworthy module M where import System IO Unsafe import safe Buggle Suppose a client C decides to trust package P Then does C trust module M To decide GHC must check M s imports M imports System IO Unsafe M was compiled with XTrustwort hy so P s author takes responsibility for that import C trusts P s author so C trusts M to only use its unsafe imports in a safe and consistent manner with respect to the API M exposes M also has a safe import of Buggle so for this import P s author takes no responsibility for the safety so GHC must check whether Buggle is
235. ad error and you haven t got a clue which bit of code is causing it compiling with prof fprof auto and running with RTS xc RTS will tell you exactly the call stack at the point the error was raised The output contains one report for each exception raised in the program the program might raise and catch several excep tions during its execution where each report looks something like this xxx Exception raised reporting due to RTS xc stack trace GHC List CAF gt evaluated by Main polynomial table_search called from Main polynomial theta_index called from Main polynomial called from Main zonal_pressure called from Main make_pressure p called from Main make_pressure called from Main compute_initial_state p called from Main compute_initial_state called from Main CAF The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 104 327 The stack trace may often begin with something uninformative like GHC List CAF this is an artifact of GHC s op timiser which lifts out exceptions to the top level where the profiling system assigns them to the cost centre CAF However RTS xc doesn t just print the current stack it looks deeper and reports the stack at the time the CAF was evaluated and it may report further stacks until a non CAF stack is found In the example above the next stack after gt evaluated by contains plenty of information about what the
236. afe Haskell is an extension to the Haskell language that is implemented in GHC as of version 7 2 It allows for unsafe code to be securely included in a trusted code base by restricting the features of GHC Haskell the code is allowed to use Put simply it makes the types of programs trustable Safe Haskell is aimed to be as minimal as possible while still providing strong enough guarantees about compiled Haskell code for more advance secure systems to be built on top of it While this is the use case that Safe Haskell was motivated by it is important to understand that what Safe Haskell is tracking and enforcing is a stricter form of type safety than is usually guaranteed in Haskell As part of this Safe Haskell is run during every compilation of GHC tracking safety and inferring it even for modules that don t explicitly use Safe Haskell Please refer to section Section 7 29 5 for more details of this This also means that there are some design choices that from a security point of view may seem strange but when thought of from the angle of tracking type safety are logical Feedback on the current design and this tension between the security and type safety view points is welcome The design of Safe Haskell covers the following aspects e A safe language dialect of Haskell that provides guarantees about the code It allows types and module boundaries to be trusted e A safe import extension that specifies that the module being imported must be trusted
237. ak down the graph by biography Biographical profiling is described in more detail below Section 5 4 3 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 138 327 In addition the profile can be restricted to heap data which satisfies certain criteria for example you might want to display a profile by type but only for data produced by a certain module or a profile by retainer for a certain type of data Restrictions are specified as follows hcname Restrict the profile to closures produced by cost centre stacks with one of the specified cost centres at the top hCname Restrict the profile to closures produced by cost centre stacks with one of the specified cost centres anywhere in the stack hmmodule Restrict the profile to closures produced by the specified modules hddesc Restrict the profile to closures with the specified description strings hytype Restrict the profile to closures with the specified types hrcc Restrict the profile to closures with retainer sets containing cost centre stacks with one of the specified cost centres at the top hbbio Restrict the profile to closures with one of the specified biographies where bio is one of lag drag void or use For example the following options will generate a retainer profile restricted to Branch and Leaf constructors prog RTS hr hdBranch Leaf There can only be one break down optio
238. al optimisations to be turned on off the m options specify machine specific optimisations to be turned on off 4 10 1 Ox convenient packages of optimisation flags 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 Note that higher optimisation levels cause more cross module optimisation to be performed which can have an impact on how much of your program needs to be recompiled when you change something This is one reason to stick to no optimisation when developing code No Ox type option 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 00 Means turn off all optimisation reverting to the same settings as if no O options had been specified Saying 00 can be useful if eg make has inserted a O on the command line already Oor O1 Means Generate good quality code without taking too long about it Thus for example ghc c O Main Ihs The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 79 327 02 Means Apply every non dangerous optimisation even if it means significantly longer compile times The avoided dangerous optimisations are those
239. al Enable only breakpoints in the current top level binding and resume evaluation at the last breakpoint stepmodule Enable only breakpoints in the current module and resume evaluation at the last breakpoint trace expr Evaluates the given expression or from the last breakpoint if no expression is given and additionally logs the evaluation steps for later inspection using history See Section 2 5 5 type expression Infers and prints the type of expression including explicit forall quantifiers for polymorphic types The monomorphism restriction is not applied to the expression during type inference undef name Undefines the user defined command name see def above unset option Unsets certain options See Section 2 8 for a list of available options command Executes the shell command command 2 8 The set and seti commands The set command sets two types of options GHCi options which begin with and command line options which begin with NOTE at the moment the set command doesn t support any kind of quoting in its arguments quotes will not be removed and cannot be used to group words together For example set DFOO BAR BAZ will not do what you expect 2 8 1 GHCi options GHCi options may be set using set and unset using unset The available GHCi options are m Enable parsing of multiline commands A multiline command is prompted for when the current input line co
240. all call sites This is particularly useful when using profiling for the purposes of generating stack traces see the function traceStack in the module Debug Trace or the xc RTS flag Section 4 17 7 for more details fprof cafs The costs of all CAFs in a module are usually attributed to one big CAF cost centre With this option all CAFs get their own cost centre An if all else fails option fno prof auto Disables any previous fprof auto fprof auto top or fprof auto exported op tions fno prof cafs Disables any previous fprof cafs option fno prof count entries Tells GHC not to collect information about how often functions are entered at runtime the entries column of the time profile for this module This tends to make the profiled code run faster and hence closer to the speed of the unprofiled code because GHC is able to optimise more aggressively if it doesn t have to maintain correct entry counts This option can be useful if you aren t interested in the entry counts for example if you only intend to do heap profiling 5 3 Time and allocation profiling To generate a time and allocation profile give one of the following RTS options to the compiled program when you run it RTS options should be enclosed between RTS RTS as usual por P or pa The p option produces a standard time profile report It is written into the file program prof The P option produces a more detailed
241. ally and vertically so that it fills the page However when preparing a series of graphs for use in a presentation it is often useful to draw a new graph using the same scale shading and ordering as a previous one The p flag causes the graph to be drawn using the parameters determined by a previous run of hp2ps on file These are extracted from file aux s Use a small box for the title t lt float gt Normally trace elements which sum to a total of less than 1 of the profile are removed from the profile The t option allows this percentage to be modified maximum 5 t0 requests no trace elements to be removed from the profile ensuring that all the data will be displayed c Generate colour output y Ignore marks Print out usage information 5 5 1 Manipulating the hp fil e Notes kindly offered by Jan Willem Maessen The FOO hp file produced when you ask for the heap profile of a program FOO is a text file with a particularly simple structure Here s a representative example with much of the actual data omitted JOB ONE DAME Wt IDE AG Les O OZ SAMPLE UNIT seconds VALUE_UNIT bytes BEGIN_SAMPLE 0 00 END_SAMPLE 0 00 BEGIN_SAMPLE 15 07 ample data PLE A a E v 10 END_SA BEGI de 1507 PES 0023 mple data ES ZAS v n END_SA mee ele BEGIN_SAMPLE 11695 47 END_SAMPLE 11695 47 The first four line
242. alone deriving declaration instead see Section 7 5 2 In each case the appropriate class must be in scope before it can be mentioned in the deriving clause 7 5 4 Deriving Typeable instances The class Typeable is very special e Typeable is kind polymorphic see Section 7 8 GHC has a custom solver for discharging constraints that involve class Typeable and handwritten instances are forbidden This ensures that the programmer cannot subert the type system by writing bogus instances e Derived instances of Typeable are ignored and may be reported as an error in a later version of the compiler e The rules for solving Typeable constraints are as follows The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 190 327 Aconcrete type constructor applied to some types instance Typeable tl Typeable t_n gt Typeable T tl t_n This rule works for any concrete type constructor including type constructors with polymorhic kinds The only restriction is that if the type constructor has a polymorhic kind then it has to be applied to all of its kinds parameters and these kinds need to be concrete 1 e they cannot mention kind variables A type variable applied to some types instance Typeable f Typeable tl Typeable t_n gt TypeabllS E AO A concrete type literal instance Typeable 0 Type natural literals instance Typeable Hello Type level symbols 7 5 5
243. also been resolved So we can ask for the value of a for example qsort hs 2 15 46 Main gt a 8 You might find it useful to use Haskell s seq function to evaluate individual thunks rather than evaluating the whole expression with force For example CSCI 5828 SAG AMA Sioiealinic seston acia else Ligieexeree qsort hs 2 15 46 Main gt seq _t1 qsort hs 2 15 46 Main gt print right acia 2s amp eze ares We evaluated only the _t1 thunk revealing the head of the list and the tail is another thunk now bound to _t2 The seq function is a little inconvenient to use here so you might want to use def to make a nicer interface left as an exercise for the reader Finally we can continue the current execution qsort hs 2 15 46 Main gt continue SGOPPeas ae gsoOreahse2o 46 results al MEE RO lerte Fal A lal qsort hs 2 15 46 Main gt The execution continued at the point it previously stopped and has now stopped at the breakpoint for a second time 2 5 1 1 Setting breakpoints Breakpoints can be set in various ways Perhaps the easiest way to set a breakpoint is to name a top level function break identifier Where identifier names any top level function in an interpreted module currently loaded into GHCi qualified names may be used The breakpoint will be set on the body of the function when it is fully applied but before any pattern matching has taken place Breakpo
244. amiliar from SQL They are fully described in the paper Comprehensive comprehensions comprehensions with order by and group by except that the syntax we use differs slightly from the paper The extension is enabled with the flag XTransformListComp Here is an example The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 166 327 employees Simon MS 80 ES OO PL Ei 0 Gordon Ha 45 Aa Male 60 r output the dept sum salary name dept salary lt employees then group by dept using groupWith then sortWith by sum salary then take 5 In this example the list output would take on the value Eat OO Mac 89 MMS MBQ There are three new keywords group by and using The functions sortWith and groupWith are not keywords they are ordinary functions that are exported by GHC Exts There are five new forms of comprehension qualifier all introduced by the existing keyword then then f This statement requires that f have the type forall a a gt a You can see an example of its use in the motivating example as this form is used to apply take 5 then f by e This form is similar to the previous one but allows you to create a function which will be passed as the first argument to f As a consequence f must have the type forall a a gt t gt a gt a As you can see from the type this func
245. and proud of it case unpackHooms Vor cul Il Si gt case Un paco oO ZO 2 C2 gt 1 GHC loves single constructor data types It s all the better if a function is strict in a single constructor type a type with only one data constructor for example tuples are single constructor types Newtypes are better than datatypes If your datatype has a single constructor with a single field use a newt ype declaration instead of a data declaration The newt ype will be optimised away in most cases How do I find out a function s strictness Don t guess look it up Look for your function in the interface file then for the third field in the pragma it should say Strictness lt string gt The lt string gt gives the strictness of the function s arguments see the GHC Commentary for a description of the strictness notation For an unpackable U argument the info inside tells the strictness of its components So if the argument is a pair and it says U AU LSS that means the first component of the pair isn t used the second component is itself unpackable with three components lazy in the first strict in the second amp third If the function isn t exported just compile with the extra flag ddump simp1 next to the signature for any binder it will print the self same pragmatic information as would be put in an interface file Besides Core syntax is fun to look at Force key functions
246. arated not inside parens Such macro is invoked as other constructs starting with name The definition will be put in the C program inside parens as arguments of printf To refer to a parameter close the quote put a parameter name and open the quote again to let C string literals concatenate Or use print f s format directives Values of arguments must be given as strings unless the macro stringifies them itself using the C preprocessor s parameter syntax The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 307 327 def C_definition The definition of a function variable struct or typedef is written to the C file and its prototype or extern declaration to the C header Inline functions are handled correctly struct definitions and typedefs are written to the C program too The inline struct or typedef keyword must come just after def if condition ifdef name ifndef name elif condition else endif error message warning Conditional compilation directives are passed unmodified to the C program C file and C header Putting them in the C program means that appropriate parts of the Haskell file will be skipped const C_expression The expression must be convertible to Long or unsigned long Its value literal or negated literal will be output const_str C_expression The expression must be convertible to const char pointer Its value string literal will be output type
247. arn implicit prelude fwarn missing local sigs fwarn missing exported sigs fwarn missing import lists and fwarn iden tities w Turns off all warnings including the standard ones and those that Wal11 doesn t enable Werror Makes any warning into a fatal error Useful so that you don t miss warnings when doing batch compilation Wwarn Warnings are treated only as warnings not as errors This is the default but can be useful to negate a Werror flag The full set of warning options is described below To turn off any warning simply give the corresponding fno warn option on the command line fwarn typed holes Determines whether the compiler reports typed holes warnings Has no effect unless typed holes errors are deferred until runtime See Section 7 14 and Section 7 16 This warning is on by default fdefer type errors Defer as many type errors as possible until runtime At compile time you get a warning instead of an error At runtime if you use a value that depends on a type error you get a runtime error but you can run any type correct parts of your code just fine See Section 7 16 fdefer typed holes Defer typed holes errors until runtime This will turn the errors produced by typed holes into warnings Using a value that depends on a typed hole produces a runtime error the same as fdefer typ rrors which implies this option See Section 7 14 and Section 7 16 Implied by fdefer typ rrors
248. as it knows what concrete type level literal is being used in the program Note that this works only for literals and not arbitrary type expressions For example a constraint of the form KnownNat a b will not be simplified to KnownNat a KnownNat b instead GHC will keep the constraint as is until it can simplify a b to a constant value It is also possible to convert a run time integer or string value to the corresponding type level literal Of course the resulting type literal will be unknown at compile time so it is hidden in an existential type The conversion may be performed using someNat Val for integers and someSymbolVal for strings someNatVal Integer gt Maybe SomeNat SomeNat KnownNat n gt Proxy n gt SomeNat The operations on strings are similar 7 10 2 Computing With Type Level Naturals GHC 7 8 can evaluate arithmetic expressions involving type level natural numbers Such expressions may be constructed using the type families x for addition multiplication and exponentiation Numbers may be compared using lt which returns a promoted boolean value or lt which compares numbers as a constraint For example GHC TypeLits gt natVal Proxy Proxy 2 3 5 At present GHC is quite limited in its reasoning about arithmetic it will only evalute the arithmetic type functions and compare the results in the same way that it does for any other type function In particular it does
249. ase We also support renaming of modules in case you need to refer to both modules simultaneously this is supporting by writing Ol dModName as NewModName e g package base Data Bool as Bool You can also write package base with Data Bool as Bool to include all of the original bindings e g the renaming is strictly additive It s important to specify quotes so that your shell passes the package name and thinning renaming list as a single argument to GHC Package imports with thinning renaming do not hide other versions of the package e g if containers 0 9 is already exposed package containers 0 8 Data List as ListV8 will only add an additional binding to the environment Similarly package base Data Bool as Bool package base Data List as List is equiva lent to package base Data Bool as Bool Data List as List Literal names must refer to modules defined by the original package so for example package base Data Bool as Bool Bool as Baz is in valid unless there was a Bool module defined in the original package Hiding a package also clears all of its renamings You can use renaming to provide an alternate prelude e g hide all packages package basic prelude Ba sicPrelude as Prelude in lieu of the Section 7 3 16 extension 4 9 5 Package Databases A package database is where the details about installed packages are stored It is a directory usually called package conf d that contains a file for each pac
250. ason hide package P This option does the opposite of package it causes the specified package to be hidden which means that none of its modules will be available for import by Haskell import directives Note that the package might still end up being linked into the final program if it is a dependency direct or indirect of another exposed package ignore package P Causes the compiler to behave as if package P and any packages that depend on P are not installed at all Saying ignore package P is the same as giving hide package flags for P and all the packages that depend on P Sometimes we don t know ahead of time which packages will be installed that depend on P which is when the ignore package flag can be useful no auto link packages By default GHC will automatically link in the base and rts packages This flag disables that behaviour this package key foo Tells GHC the the module being compiled forms part of package key foo internally these keys are used to determine type equality and linker symbols If this flag is omitted a very common case then the default package main is assumed trust P This option causes the install package P to be both exposed and trusted by GHC This command functions in the in a very similar way to the package command but in addition sets the selected packaged to be trusted by GHC regardless of the contents of the package database see Section 7 29 distrust P This option cause
251. ass you can derive any other class The compiler will simply generate an empty instance The instance context will be generated according to the same rules used when deriving Eq This is mostly useful in classes whose minimal set is empty and especially when writing generic functions In case you try to derive some class on a newtype and XGeneraliz edNewt ypeDeriving is also on XDeriveAnyClass takes precedence 7 6 Class and instances declarations 7 6 1 Class declarations This section and the next one documents GHC s type class extensions There s lots of background in the paper Type classes exploring the design space Simon Peyton Jones Mark Jones Erik Meijer 7 6 1 1 Multi parameter type classes Multi parameter type classes are permitted with flag XMultiParamTypeClasses For example class Collection c a where Uae 382 CA gt a gt A LOs 7 6 1 2 The superclasses of a class declaration In Haskell 98 the context of a class declaration which introduces superclasses must be simple that is each predicate must consist of a class applied to type variables The flag XFlexibleContexts Section 7 13 2 lifts this restriction so that the only restriction on the context in a class declaration is that the class hierarchy must be acyclic So these class declarations are OK The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 193 327 class Functor m k gt FiniteMap m k where
252. at run time and generate a call tree of cost attributions Let s take a look at an example metia force Gestion 10 fib m af m lt 2 then 1 else tib Ll fab a 2 Compile and run this program as follows ghe prof fprof auto rtsopts Main hs Soe Main RES p 121398 When a GHC compiled program is run with the p RTS option it generates a file called prog prof In this case the file will contain something like this l fprof auto was known as auto a11 prior to GHC 7 4 1 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 133 327 Wed Oct 12 16 14 2011 Time and Allocation Profiling Report MAITE EMS OS total time 0 68 toral ellos 204 677 844 COST CENTRE MODULE time Salloc i allo Main 100 0 LOO 0 COST CENTRE MODULE MAIN MAIN CAF GHC 1I0 Handle FD CAF GHC 10 Encoding Iconv CAF GHC Conc Signal CAF Main main Main Talo Main secs bytes no 102 123 120 LLG 108 204 205 34 ticks 20 ms Final excludes profiling overheads entries 0 0 0 0 0 ll 7 269253 individual Stime 10 SQ Gags SS fey s tsi SY SS Salloc eS Cx Goo SS Sener ee gt 10 inherited Stime Salloc 100 0 100 0 omo 0 0 0 0 0 0 ORO 0 0 100 0 100 0 100 0 1000 100 0 100 0 The first part of the file gives the program name and options and the total time and total memory allocation measured
253. at use exotic sorts of constraints in instance contexts and superclasses but to do so you must use XUndecidablelnstances to signal that you don t mind if the type checker fails to terminate 7 13 Other type system extensions 7 13 1 Explicit universal quantification forall Haskell type signatures are implicitly quantified When the language option XExplicitForAll is used the keyword for all allows us to say exactly what this means For example a 8 lo gt Ip means this e 28 oral los Us gt 19 The two are treated identically Of course forall becomes a keyword you can t use forall as a type variable any more 7 13 2 The context of a type signature The XFlexibleContexts flag lifts the Haskell 98 restriction that the type class constraints in a type signature must have the form class type variable or class type variable typel type2 typen With XF lexibleContexts these type signatures are perfectly OK a ss ise el gt oes G gs Omre w a Q gt The flag XFlexibleContexts also lifts the corresponding restriction on class declarations Section 7 6 1 2 and instance declarations Section 7 6 3 3 7 13 3 Ambiguous types and the ambiguity check Each user written type signature is subjected to an ambiguity check The ambiguity check rejects functions that can never be called for example The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 226 327
254. ata T T UNPACK 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 UNPACK S data S S UNPACK Int UNPACK Int will store two unboxed Int s directly in the T constructor The unpacker can see through newtypes too See also the funbox strict fields flag which essentially has the effect of adding UNPACK to every strict constructor field 7 22 12 NOUNPACK pragma The NOUNPACK pragma indicates to the compiler that it should not unpack the contents of a constructor field Example Glaiea i NO UNE ACES E Even with the flags funbox strict fields and O the field of the constructor T is not unpacked 7 22 13 SOURCE pragma E The SOURCE pragma is used only in import declarations to break a module loop It is described in detail in Section 4 7 9 lin fact UNPACK has no effect without O for technical reasons see tick 5252 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 268 327 7 22 14 OVERLAPPING OVERLAPPABLE OVERLAPS and INCOHERENT pragmas The pragmas OVERLAPP ING OVERLAPPABLE OVERLAPS INCOHERENT are used to specify the overlap behavior for indi vidual instances as described in Section Section 7 6 3 5 The pragmas are written immediately after the instance keyword like this instance
255. atch the result of that application against the pattern The expression can be any Haskell expression of function type and view patterns can be used wherever patterns are used The semantics of a pattern exp gt pat are as follows e Scoping The variables bound by the view pattern are the variables bound by pat Any variables in exp are bound occurrences but variables bound to the left in a pattern are in scope This feature permits for example one argument to a function to be used in the view of another argument For example the function clunky from Section 7 3 7 can be written using view patterns as follows clunky env lookup env gt Just vall lookup env gt Just val2 vall val2 co Oli Suele HOM sme Ors Cubo os More precisely the scoping rules are Ina single pattern variables bound by patterns to the left of a view pattern expression are in scope For example example Maybe String gt Integer Integer String gt Bool example Just f _ f gt 4 True Additionally in function definitions variables bound by matching earlier curried arguments may be used in view pattern expressions in later arguments example String gt Integer gt String gt Bool xample f f gt 4 Tru That is the scoping is the same as it would be if the curried arguments were collected into a tuple In mutually recursive bindings such as let where or the top level view patterns in one d
256. aths relative to the program or library itself In principle this makes 1t possible to construct fully relocatable sets of programs and libraries GHC has a dynload linking flag to select the method that is used to find shared libraries at runtime There are currently two modes sysdep A system dependent mode This is also the default mode On Unix ELF systems this embeds RPATH RUNPATH entries into the shared library or executable In particular 1t uses absolute paths to where the shared libraries for the rts and each package can be found This means the program can immediately be run and it will be able to find the libraries it needs However it may not be suitable for deployment if the libraries are installed in a different location on another machine deploy This does not embed any runtime paths It relies on the shared libraries being available in a standard location or in a directory given by the LD_LIBRARY_PATH environment variable To use relative paths for dependent libraries on Linux and Solaris you can pass a suitable rpath flag to the linker cis eyaemio Mesta las 0 meta EOS Ls Oe LA get SO Lali Gina This assumes that the library 1ibfoo so is in the current directory and will be able to be found in the same directory as the executable main once the program is deployed Similarly it would be possible to use a subdirectory relative to the executable e g opt1l Wl rpath SORIGIN 1lib This relative path technique can be
257. ation area will be resized according to the amount of data in the heap see F below nsize Default 0 Example n4m When set to a non zero value this option divides the allocation area A value into c chunks of the specified size During execution when a processor exhausts its current chunk it is given another chunk from the pool until the pool is exhausted at which point a collection is triggered This option is only useful when running in parallel N2 or greater It allows the processor cores to make better use of the available allocation area even when cores are allocating at different rates Without n each core gets a fixed size allocation area specified by the A and the first core to exhaust its allocation area triggers a GC across all the cores This can result in a collection happening when the allocation areas of some cores are only partially full so the purpose of the n is to allow cores that are allocating faster to get more of the allocation area This means less frequent GC leading a lower GC overhead for the same heap size This is particularly useful in conjunction with larger A values for example A64m n4mis a useful combination on larger core counts 8 Use a compacting algorithm for collecting the oldest generation By default the oldest generation is collected using a copying algorithm this option causes it to be compacted in place instead The compaction algorithm is slower than the copyi
258. ation of Template Haskell in GHC It is not detailed enough to understand Template Haskell see the Wiki page 7 17 1 Syntax Template Haskell has the following new syntactic constructions You need to use the flag XTemplateHaskell to switch these syntactic extensions on e A splice is written x where x is an identifier or where the is an arbitrary expression There must be no space between the and the identifier or parenthesis This use of overrides its meaning as an infix operator just as M x overrides the meaning of as an infix operator If you want the infix operator put spaces around it A splice can occur in place of an expression the spliced expression must have type O Exp a pattern the spliced pattern must have type Q Pat a type the spliced expression must have type O Type a list of declarations at top level the spliced expression must have type Q Dec Inside a splice you can only call functions defined in imported modules not functions defined elsewhere in the same module Note that declaration splices are not allowed anywhere except at top level outside any other declarations e A expression quotation is written in Oxford brackets thus or el where the is an expression the quotation has type O Exp dl 1 where the is a list of top level declarations the quotation has type Q Dec t where the is a type th
259. ault fwarn deprecated flags Causes a warning to be emitted when a deprecated commandline flag is used This option is on by default The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 62 327 fwarn unsupported calling conventions Causes a warning to be emitted for foreign declarations that use un supported calling conventions In particular if the st dcal1 calling convention is used on an architecture other than 1386 then it will be treated as ccall fwarn dodgy foreign imports Causes a warning to be emitted for foreign imports of the following form POLENON Jonas Wie ae ge Moi ic on the grounds that it probably should be POLENG impor Vesey dE 88 ENWP e The first form declares that f is a pure C function that takes no arguments and returns a pointer to a C function with type t whereas the second form declares that f itself is a C function with type t The first declaration is usually a mistake and one that is hard to debug because it results in a crash hence this warning fwarn dodgy exports Causes a warning to be emitted when a datatype T is exported with all constructors i e T but is it just a type synonym Also causes a warning to be emitted when a module is re exported but that module exports nothing fwarn dodgy imports Causes a warning to be emitted in the following cases e When a datatype T is imported with all constructors i e T but has been exp
260. ay is heap allocated because it is too big a value to fit in a register and would be too expensive to copy around in a sense it is accidental that it is represented by a pointer If a pointer represents a primitive value then it really does point to that value no unevaluated thunks no indirections nothing can be at the other end of the pointer than the primitive value A numerically intensive program using unboxed types can go a lot faster than its standard counterpart we saw a threefold speedup on one example There are some restrictions on the use of primitive types e The main restriction is that you can t pass a primitive value to a polymorphic function or store one in a polymorphic data type This rules out things like Int i e lists of primitive integers The reason for this restriction is that polymorphic arguments and constructor fields are assumed to be pointers if an unboxed integer is stored in one of these the garbage collector would attempt to follow it leading to unpredictable space leaks Or a seq operation on the polymorphic component may attempt to dereference the pointer with disastrous results Even worse the unboxed value might be larger than a pointer Double for instance e You cannot define a newtype whose representation type the argument type of the data constructor is an unboxed type Thus this is illegal newtype A MkA Int e You cannot bind a variable with an unbox
261. b complete names that are in scope for example if you run GHCi and type J lt t ab gt then GHCi will expand itto Just 2 4 5 1 The effect of load on what is in scope The load add and reload commands Section 2 2 and Section 2 3 affect the top level scope Let s start with the simple cases when you start GHCi the prompt looks like this Prelude gt which indicates that everything from the module Prelude is currently in scope the visible identifiers are exactly those that would be visible in a Haskell source file with no import declarations If we now load a file into GHCi the prompt will change Prelude gt load Main hs Compiling Main Main hs interpreted Main gt The new prompt is Main which indicates that we are typing expressions in the context of the top level of the Main module Everything that is in scope at the top level in the module Main we just loaded is also in scope at the prompt probably including Prelude as long as Main doesn t explicitly hide it The syntax in the prompt module indicates that it is the full top level scope of module that is contributing to the scope for expressions typed at the prompt Without the just the exports of the module are visible The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 20 327 NOTE for technical reasons GHCi can only support the form for modules that are interpreted Compiled modules and package modules can
262. b sites mailing lists etc On the World Wide Web there are several URLs of likely interest e GHC home page e GHC Developers Home developer documentation wiki and bug tracker We run the following mailing lists about GHC We encourage you to join as you feel is appropriate The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 2 327 glasgow haskell users This list is for GHC users to chat among themselves If you have a specific question about GHC please check the FAQ first list email address glasgow haskell users haskell org subscribe at http www haskell org mailman listinfo glasgow haskell users admin email address glasgow haskell users admin haskell org list archives http www haskell org pipermail glasgow haskell users ghc devs The hardcore GHC developers hang out here list email address ghc devs haskell org subscribe at http www haskell org mailman listinfo ghc devs admin email address ghc devs adminO haskell org list archives http www haskell org pipermail ghc devs There are several other haskell and GHC related mailing lists served by www haskell org Goto http www hask ell org mailman listinfo for the full list Some Haskell related discussion also takes place in the Usenet newsgroup comp lang functional 1 3 Reporting bugs in GHC Glasgow Haskell is a changing system so there are sure to be bugs in it If you find one please see this wiki page
263. be ensured before it is called e g ifdef MIN_VERSION_GLASGOW_HASKELL if MIN_VERSION_GLASGOW_HASKELL 7 10 2 0 x code that applies only to GHC 7 10 2 or later x tendif tendif The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 87 327 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 1hs c and hc files __ GLASGOW_HASKELL TH__ This is set to YES when the compiler supports Template Haskell and to NO when not The latter is the case for a stage 1 compiler during bootstrapping or on architectures where the interpreter is not available ___GLASGOW_HASKELL_LLVM__ Only defined when f11vm is specified When GHC is using version x y z of LLVM the value of __GLASGOW_HASKELL_LLVM__ is the integer xy __ PARALLEL HASKELL Only defined when parallel is in use This symbol is defined when pre processing Haskell input and pre processing C GHC output os_HOST_OS 1 This define allows conditional compilation based on the Operating System whereos is the name of the current Operating System eg Linux mingw32 for Windows solaris etc arch_HOST_ARCH 1 This define allows conditional compilation based on the host architecture wherearch is the name of the current architecture eg 1386 x86_64 powerpc sparc etc 4 12 3 1 CPP and string gaps A small word of warning
264. binary cache file package cache for the selected database This may be necessary if the cache has somehow become out of sync with the contents of the database ghc pkg will warn you if this might be the case The other time when ghc pkg recache is useful is for registering packages manually it is possible to register a package by simply putting the appropriate file in the package database directory and invoking ghc pkg recache to update the cache This method of registering packages may be more convenient for automated packaging systems Substring matching is supported for M in find module and for P in list describe and field where a x indicates open substring ends prefixx suffix infixx Examples output omitted list all regex related packages ghc pkg list x regexx ignore cas list all string related packages ghc pkg list xstring ignore case list OpenGL related packages ghc pkg list xglx ignore case list packages exporting modules in the Data hierarchy ghc pkg find module Data x list packages exporting Monad modules ghc pkg find module Monad list names and maintainers for all packages ghc pkg field name maintainer list location of haddock htmls for all packages ghc pkg field haddock html dump the whole database ghc pkg describe x Additionally the following flags are accepted by ghc pkg f file package db file Adds file to the
265. bindings Show the bindings made at the prompt and their types The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 38 327 show breaks List the active breakpoints show context List the active evaluations that are stopped at breakpoints show imports Show the imports that are currently in force as created by import and module commands show modules Show the list of modules currently loaded show packages Show the currently active package flags as well as the list of packages currently loaded show paths Show the current working directory as set via cd command as well as the list of directories searched for source files as set by the i option show language Show the currently active language flags for source files showi language Show the currently active language flags for expressions typed at the prompt see also set i show args prog prompt editor stop Displays the specified setting see set sprint Prints a value without forcing its evaluation sprint is similar to print with the difference that unevaluated subterms are not bound to new variables they are simply denoted by _ step expr Enable all breakpoints and begin evaluating an expression in single stepping mode In this mode evaluation will be stopped after every reduction allowing local variables to be inspected If expr is not given evaluation will resume at the last breakpoint See Section 2 5 2 steploc
266. boilerplate code for the specified class and typechecks it If there is a type error it is your problem GHC will show you the offending code if it has a type error The merit of this is that you can derive instances for GADTs and other exotic data types providing only that the boilerplate code does indeed typecheck For example data T a where IgE dae UE SB Bool deriving instance Show T a The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 189 327 In this example you cannot say deriving Show on the data type declaration for T because T is a GADT but you can generate the instance declaration using stand alone deriving The down side is that if the boilerplate code fails to typecheck you will get an error message about that code which you did not write Whereas with a deriving clause the side conditions are necessarily more conservative but any error message may be more comprehensible In other ways however a standalone deriving obeys the same rules as ordinary deriving e Aderiving instance declaration must obey the same rules concerning form and termination as ordinary instance dec larations controlled by the same flags see Section 7 6 3 e The stand alone syntax is generalised for newtypes in exactly the same way that ordinary deriving clauses are generalised Section 7 5 5 For example newtype Foo a MkFoo Stat e Int a deriving instance MonadState In
267. c2hs command can be used to automate some parts of the process of writing Haskell bindings to C code It reads an almost Haskell source with embedded special constructs and outputs a real Haskell file with these constructs processed based on information taken from some C headers The extra constructs deal with accessing C data from Haskell It may also output a C file which contains additional C functions to be linked into the program together with a C header that gets included into the C code to which the Haskell module will be compiled when compiled via C and into the C file These two files are created when the def construct is used see below Actually hsc2hs does not output the Haskell file directly It creates a C program that includes the headers gets automatically compiled and run That program outputs the Haskell code In the following Haskell file is the main output usually a hs file compiled Haskell file is the Haskell file after ghc has compiled it to C i e a hc file C program is the program that outputs the Haskell file C file is the optionally generated C file and C header is its header file 11 2 1 command line syntax hsc2hs takes input files as arguments and flags that modify its behavior o FILE or output FILE Name of the Haskell file t FILE or template FILE The template file see below c PROG or cc PROG The C compiler to use default gec 1 PROG or 1d PROG T
268. call arity optimisation Implied by dynamic fno call arity O p oe Enable case merging ia bn nae case merge Implied by 0 y fno cas g f Enable Cmm common 7 fcmm el im common Se fno cmm elim block elimination Implied dynamic blocks common blocks by O Enabl inking a fcmm sink me te Cm SSRS dynamic fno cmm sink Implied by 0 itch off CPR analysis 1 fcpr ff Switch off CPR analysis in a the demand analyser Enable common fcse sub expression elimination dynamic fno cse Implied by 0 Make dictionary valued fdicts cheap expressions seem cheap to dynamic fno dicts cheap the optimiser fdicts strict Make dictionaries strict dynamic fno dicts strict Use a special demand anida transformer for dictionary dynamit fno dmd tx dict selectors Always enabled sel by default Enable eta reduction i fno do eta fdo eta reduction dynamic Implied by o reduction Enable lambd fdo lambda eta SR e a fno do lambda n eta expansion Always dynamic Ste apene ton p enabled by default f bl aes ting Turn on eager blackholing dynamic Switch on all rewrite rules fenable rewrit peace me pencas fno enable by automatic specialisation dynamic rules rewrite rules of overloaded functions Implied by O a Enable excess intermediate fno excess fexcess precision dynamic he precision precision E ll unfoldi fexpose all E MON fno expose all for very large or recursive dynamic unfo
269. can mallocForeignPtr Useful for longer term allocation which requires garbage collection If you intend to store the pointer to the memory in a foreign data structure then mal locForeignPt r is not a good choice however In GHC mallocForeignPtr is also implemented using MutableByteArray Although the memory is pointed to by a ForeignPtr there are no actual finalizers involved unless you add one with addForeignPtrFinalizer and the deallocation is done using GC so mallocForeignPtr is normally very cheap malloc free If all else fails then you need to resort to Foreign malloc and Foreign free These are just wrappers around the C functions of the same name and their efficiency will depend ultimately on the implementations of these functions in your platform s C library We usually find malloc and free to be significantly slower than the other forms of allocation above Foreign Marshal Pool Pools are currently implemented using malloc free so while they might be a more convenient way to structure your memory allocation than using one of the other forms of allocation they won t be any more efficient We do plan to provide an improved performance implementation of Pools in the future however The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 294 327 8 2 4 Multi threading and the FFI In order to use the FFI in a multi threaded setting you must use the threaded option see Section 4 12 6 8 2
270. cation developers can check this into their repository so that they can grep for identifiers used elsewhere that were defined in Template Haskell This is similar to using ddump to file with ddump splices but it always generates a file instead of being coupled to ddump to file and only outputs code that does not exist in the hs file and a comment for the splice location in the original fi 1 5 2 3 GHCi e It s now possible to use set 1 f00 in GHCi to link against a foreign library after startup e Pattern synonyms are now supported in GHCi 1 5 2 4 Template Haskell e Added support for generating LINE pragma declarations Section 7 22 7 e The type Pred which stores a type constraint is now a synonym for Type in order to work with the Const raintKinds extension This is a breaking change and may require some rewriting of Template Haskell code e Pattern splices now work e reifyInstances now treats unbound type variables as univerally quantified allowing lookup of say the instance for 1 a E Q e More kind annotations appear in reified types in order to disambiguate types that would otherwise be ambiguous in the presence of PolyKinds In particular all reified TyVarBndrs are now KindedTVs This does not affect Template Haskell quotations just calls to rei f y e Various features unsupported in quotations were previously silently ignored These now cause errors e Lift instances were added for many more
271. checking GHC has a number of options that select which types of non fatal error messages otherwise known as warnings can be gen erated during compilation By default you get a standard set of warnings which are generally likely to indicate bugs in your program These are fwarn overlapping patterns fwarn warnings deprecations fwarn deprec ated flags fwarn unrecognised pragmas fwarn pointless pragmas fwarn duplicate cons traints fwarn duplicate exports fwarn overflowed literals fwarn empty enumerations fwarn missing fields fwarn missing methods fwarn wrong do bind fwarn unsupported calling conventions fwarn dodgy foreign imports fwarn inline rule shadowing fwarn unsupported llvm version fwarn context quantification and fwarn tabs The following flags are simple ways to select standard packages of warnings W Provides the standard warnings plus fwarn unused binds fwarn unused matches fwarn unused imports fwarn incomplete patterns fwarn dodgy exports and fwarn dodgy imports The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 61 327 Wal1 Turns on all warning options that indicate potentially suspicious code The warnings that are not enabled by Wall are fwarn incomplete uni patterns fwarn incomplete record updates fwarn mon omorphism restriction fwarn auto orphans fw
272. ckage 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 Don t forget to use the same package options on the ghc M command line as you would when compiling this enables the dependency generator to locate any imported modules that come from packages The package modules won t be included in the dependencies generated though but see the include pkg deps option below The dependency generation phase of GHC can take some additional options which you may find useful The options which affect dependency generation are ddump mod cycles Display a list of the cycles in the module graph This is useful when trying to eliminate such cycles v2 Print a full list of the module dependencies to stdout This is the standard verbosity flag so the list will also be displayed with v3 and v4 Section 4 6 dep makefile file Use file as the makefile rather than makefile or Makefile If file doesn t exist mkde pendHS creates it We often use dep makefile depend to put the dependencies in depend and then include the file depend into Makef ile dep suffix lt suf gt Make ext
273. class declarations A role annotation declaration starts with type role and is followed by one role listing for each parameter of the type This parameter count includes parameters implicitly specified by a kind signature in a GADT style data or newtype declaration Each role listing is a role nominal representational or phantom ora _ Using a _ says that GHC should infer that role The role annotation may go anywhere in the same module as the datatype or class definition much like a value level type signature Here are some examples The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 278 1 327 type role T1 _ phantom data Tl a b MkTl a b is not used annotation is fine but unnecessary type role T2 _ phantom data T2 a b MkT2 b ERROR b is used and cannot be phantom type role T3 _ nominal data T3 a b MkT3 a OK nominal is higher than necessary but safe type role T4 nominal data T4 a MkT4 a Int OK but nominal is higher than necessary type role C representational _ OK with XIncoherentInstances class C a b where OK b will get a nominal role type role X nominal type X GS gas ERROR role annotations not allowed for type synonyms 7 28 Concurrent and Parallel Haskell GHC implements some major extensions to Haskell to support concurrent and parallel programming Let us first establish terminology e Parallelism means running a Haskell program
274. class typel typem where The part before the gt is the context while the part after the gt is the head of the instance declaration 7 6 3 1 Instance resolution When GHC tries to resolve say the constraint C Int Bool it tries to match every instance declaration against the constraint by instantiating the head of the instance declaration Consider these declarations instance contextl gt C Int a where A instance context2 gt Ca Bool where B GHC s default behaviour is that exactly one instance must match the constraint it is trying to resolve For example the constraint C Int Bool matches instances A and B and hence would be rejected while C Int Char matches only A and hence A is chosen Notice that e When matching GHC takes no account of the context of the instance declaration context 1 etc e It is fine for there to be a potential of overlap by including both declarations A and B say an error is only reported if a particular constraint matches more than one See also Section 7 6 3 5 for flags that loosen the instance resolution rules 7 6 3 2 Relaxed rules for the instance head In Haskell 98 the head of an instance declaration must be of the form C T al an where C is the class T is a data type constructor and the a1 an are distinct type variables In the case of multi parameter type classes this rule applies to each parameter of the instance head Arguably it
275. closed type families Although all open type families are considered to have a complete user specified kind signature we can relax this condition for closed type families where we have equations on which to perform kind inference GHC will infer kinds for the arguments and result types of a closed type family GHC supports kind indexed type families where the family matches both on the kind and type GHC will not infer this behaviour without a complete user supplied kind signature as doing so would sometimes infer non principal types For example The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 219 327 type family Fl a where Fl True False Fl False True TL 32 Xx Fl fails to compile kind indexing is not inferred type family F2 a k where F2 True False F2 False True PQ oe xX F2 fails to compile no complete signature type family F3 a k k where F3 True False F3 False True T x x OK 7 8 5 Kind inference in class instance declarations Consider the following example of a poly kinded class and an instance for it class C a where type E a instance C b where mas de la l gt 19 In the class declaration nothing constrains the kind of the type a so it becomes a poly kinded type variable a k Yet in the instance declaration the right hand side of the associated type instance b gt b says that b must be of kind GHC could theoretica
276. code 88 fcall arity 79 femm sink 79 fcpr Off 79 fcse 79 fdefer type errors 61 fdefer typed holes 61 fdmd tx dict sel 79 felim common blocks 79 ferror spans 50 fexcess precision 80 318 fforce recomp 54 ffull laziness 80 ffun to thunk 80 fghci hist size 29 fglasgow exts 152 fhelpful errors 61 fignore asserts 80 258 fignore interface pragmas 80 flate dmd anal 80 fliberate case 80 fliberate case threshold 80 filvm 88 floopification 80 fmax inline alloc size 80 fmax inline memcpy insn 80 fmax inline memset insns 81 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 321 327 fmax relevant bindings 81 fmax simplifier iterations 81 fmax worker args 81 fno options GHC 79 fno code 88 fno embed manifest 91 fno force recomp 54 fno gen manifest 90 fno implicit import qualified 21 fno opt coercion 81 fno pre inlining 81 fno print bind result 16 fno prof cafs 136 fno prof count entries 136 fno shared implib 91 fno state hack 81 fobject code 88 fomit interface pragmas 81 fomit yields 81 fpackage trust 284 fpedantic bottoms 81 fprint bind result 16 fprint explicit foralls 49 fprint explicit kinds 49 fprof auto 132 135 fprof auto calls 136 fprof auto top 135 fprof cafs 135 136 framework 88 framework path 89 fregs graph 81 fregs iterative 81 fsimpl tick factor 81
277. contains multiple versions of a certain package due to dependencies from other packages None of these scenarios gives rise to an error on its own but they may have some interesting consequences For instance if you have a type M T from version 1 of package P then this is not the same as the type M T from version 2 of package P and GHC will report an error if you try to use one where the other is expected Formally speaking in Haskell 98 an entity function type or class in a program is uniquely identified by the pair of the module name in which it is defined and its name In GHC an entity is uniquely defined by a triple package module and name 4 9 4 Thinning and renaming modules When incorporating packages from multiple sources you may end up in a situation where multiple packages publish modules with the same name Previously the only way to distinguish between these modules was to use title However since GHC 7 10 the package flags and their variants have been extended to allow a user to explicitly control what modules a package brings into scope by analogy to the import lists that users can attach to module imports The basic syntax is that instead of specifying a package name P to the package flag package instead we specify both a package name and a parenthesized comma separated list of module names to import For example package base Data List Data Bool makes only Data List and Data Bool visible from package b
278. context main Stopped at gqsort hs 2 15 46 gt epore 3 Stopped Matrgsoneshsin Ey ISS Lemos Jase lL 0 S555 Aci To abandon the current evaluation use abandon qsort hs 1 0 3 55 Main gt abandon qsort hs 2 15 46 Main gt abandon Main gt 2 5 4 The _result variable When stopped at a breakpoint or single step GHCi binds the variable _result to the value of the currently active expression The value of _result is presumably not available yet because we stopped its evaluation but it can be forced if the type is known and showable then just entering _result at the prompt will show it However there s one caveat to doing this evaluating _result will be likely to trigger further breakpoints starting with the breakpoint we are currently stopped at if we stopped at a real breakpoint rather than due to step So it will probably be necessary to issue a cont inue immediately when evaluating _result Alternatively you can use force which ignores breakpoints 2 5 5 Tracing and history A question that we often want to ask when debugging a program is how did I get here Traditional imperative debuggers usually provide some kind of stack tracing feature that lets you see the stack of active function calls sometimes called the lexical call stack describing a path through the code to the current location Unfortunately this is hard to provide in Haskell because execution proceeds on a dema
279. ction in a module and call it from within a splice in the same module It would make sense to do so but it s hard to implement You can only run a function at compile time if it is imported from another module that is not part of a mutually recursive group of modules that includes the module currently being compiled Furthermore all of the modules of the mutually recursive group must be reachable by non SOURCE imports from the module where the splice is to be run For example when compiling module A you can only run Template Haskell functions imported from B if B does not import A directly or indirectly The reason should be clear to run B we must compile and run A but we are currently type checking A If you are building GHC from source you need at least a stage 2 bootstrap compiler to run Template Haskell A stage 1 compiler will reject the TH constructs Reason TH compiles and runs a program and then looks at the result So it s important that the program it compiles produces results whose representations are identical to those of the compiler itself The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 247 1327 Template Haskell works in any mode make interactive or file at a time There used to be a restriction to the former two but that restriction has been lifted 7 17 3 Viewing Template Haskell generated code The flag ddump splices shows the expansion of all top level decla
280. ctionality outweighed the cost of a small change to this rarely used interface 1 6 3 Known bugs For issues dealing with language changes please see the GHC 7 10 Migration Guide on the GHC wiki A bug in the simplifier which can cause it to totally fail to compile certain programs that get very large at compile time is known issue 10527 GHC s LLVM backend does not support LLVM 3 4 issue 9929 On Mac OS X the threaded Garbage Collector currently suffers from a large performance penalty due to a lack of system specific optimization issue 7602 GHCi fails to appropriately load dyn_o files issue 8736 Not all cases of non terminating type level computation with both recursive type families and recursive newtypes are caught This means that GHC might hang but it should do so only when the program is ill typed due to non terminating type level features The bugs are reported as 7788 and 10139 There also remain certain obscure scenarios where the solver for Coercible instances is known to be still incomplete See comments in 10079 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 12 327 Chapter 2 Using GHCi GHCi is GHC s interactive environment in which Haskell expressions can be interactively evaluated and programs can be inter preted If you re familiar with Hugs then you ll be right at home with GHCi However GHCi also has support for interactively loading c
281. ctions as Template Haskell e g in the example expr cannot be defined in Main hs where it is used but must be imported file Main hs module Main where import Expr MA TOR main do print eval expr 1 2 Faas Celene spo lors Llegar alone sin gt arra a ee gt return file Expr hs module Expr where The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 250 327 import qualified Language Haskell TH as TH import Language Haskell TH Quote data Expr IntExpr Integer AntiIntExpr String BinopExpr BinOp Expr Expr AntiExpr String deriving Show Typeable Data data BinOp AddOp subOp MulOp DivOp deriving Show Typeable Data eval Expr gt Integer eval IntExpr n n eval BinopExpr op x y opToFun op eval x eval y where opToFun AddOp oplonunSubOps SS opToFun MulOp x opToFun DivOp div expr QuasiQuoter quoteExp parseExprExp quotePat parseExprPat Parse an Expr returning its representation as either a legs ie A OQ Pats the referenced paper for how to use SYB to do this by writing a single parser of type String gt Expr instead of two SCpPparare parsers parseExprExp String gt O Exp parseExprExp SEUS yore sie 28 Sieseslievs gt 10 1XEke parseExprPat Now ru
282. ctive imports file 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 show iface file where file is the name of an interface file dumps the contents of that interface in a human readable ish format See Section 4 5 4 7 8 The recompilation checker fforce recomp Turn off recompilation checking which is on by default Recompilation checking normally stops com pilation 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 module A might require module C to be recompiled and hence when A hi changes we should check whether C should be recompiled However the dependencies of C will only list B hi not A hi 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 calculates a fingerprin
283. d and bind the result to x We can then use x in future statements for example to print it as we did above If fprint bind result is set then GHCi will print the result of a statement if and only if e The statement is not a binding or it is a monadic binding p lt e that binds exactly one variable e The variable s type is not polymorphic is not and is an instance of Show Of course you can also bind normal non IO expressions using the 1et statement Prelude gt let x 42 Prelude gt x 42 Prelude gt Another important difference between the two types of binding is that the monadic bind p lt e is strict it evaluates e whereas with the 1et form the expression isn t evaluated immediately Prelude gt let x error help Prelude gt print x xxx Exception help Prelude gt Note that 1et bindings do not automatically print the value bound unlike monadic bindings Hint you can also use 1et statements to define functions at the prompt The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 17 327 Prelude gt let add ab a b Prelude gt add 1 2 3 Prelude gt However this quickly gets tedious when defining functions with multiple clauses or groups of mutually recursive functions because the complete definition has to be given on a single line using explicit braces and semicolons instead of layout Prelude CE 31 oS i EE wl im age O PEO OI P
284. d Id and nothing more and furthermore the amount of platform specific code that needs to be written in order to get unregisterised compilation going is usually fairly small Unregisterised compilation cannot be selected at compile time you have to build GHC with the appropriate options set Consult the GHC Building Guide for details You can check if your GHC is unregisterised by calling ghc info The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 85 327 4 12 Options related to a particular phase 4 12 1 Replacing the program for one or more phases You may specify that a different program be used for one of the phases of the compilation system in place of whatever the ghe 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 phase pgmL cmd Use cmd as the literate pre processor pgmP cmd Use cmd as the C pre processor with cpp only pgme cmd Use cmd as the C compiler pgmlo cmd Use cmd as the LLVM optimiser pgmlc cmd Use cmd as the LLVM compiler pgms cmd Use cmd as the splitter pgma cmd Use cmd as the assembler pgml cmd Use cmd as the linker pgmdll cmd Use cmd as the DLL generator pgmF cmd Use cmd as the pre processor with F only pgmwindres cmd Use cmd as the program to use for embedding manifests on Windows Normally this is the program win
285. d support for single file style package databases Since version 6 12 ghc pkg has defaulted to a new database format using a directory of files one per package plus a binary cache This change will not affect programs and scripts that use ghc pkg init to create package databases This will affect scripts that create package databases using tricks like echo gt package conf Such scripts will need to be modified to use ghc pkg init and to delete databases by directory removal rather than simple file delete 1 5 3 Libraries 4 1 5 3 1 array Version number 0 5 1 0 was 0 5 0 0 5 3 2 base Version number 4 8 0 0 was 4 7 0 0 A new module GHC SrcLoc was added exporting a new type SrcLoc A SrcLoc contains package module and file names as well as start and end positions A new type CallStack was added for use with the new implicit callstack parameters A CallStack isa String SrcLoc sorted by most recent call GHC has had its internal Unicode database for parsing updated to the Unicode 7 0 standard Attempting to access a portion of the result of System 10 hGetContents that was not yet read when the handle was closed now throws an exception Previously a lazy read from a closed handle would simply end the result string leading to silent or delayed failures The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 71327 1 5 3 3 bin package db This is an internal package a
286. dance Always enabled dynamic vectorisation avoidance by default avoidance Enable vectorisation of fvectorise dynamic fno vectorise nested data parallelism 4 19 16 Profiling options Chapter 5 Flag Description Static Dynamic Reverse prof Turn on profiling dynamic Auto add SCCs to all fprof auto bindings not marked dynamic fno prof auto INLINE Auto add SCCs to all fprof auto top top level bindings not dynamic fno prof auto marked INLINE Auto add SCCs to all fprof auto Eg A B d exported bindings not dynamic fno prof auto expo marked INLINE fprof cafs Auto add SCCs to all CAFs dynamic fno prof cafs f f f f je ee Do not collect entry counts dynamic pro oia entries entries sticky Turn on ticky ticky dynamic i profiling 4 19 17 Program coverage options Section 5 7 Flag Description Static Dynamic Reverse rupe Turn on Haskell program dpan E coverage instrumentation The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 125 327 Flag Description Static Dynamic Reverse Directory to deposit mix hpedir dir files during compilation dynamic Sl default is hpc 4 19 18 Haskell pre processor options Section 4 12 4 Flag Description Static Dynamic Reverse Enable the use of a F pre processor set with dynamic pgmF 4 19 19 C pre
287. dby a ao aa Give arguments to a plugin is alae aie module ae dE dynamic Section 4 12 1 4 19 23 Replacing phases The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 128 327 Flag Description Static Dynamic Reverse Use cmd as the literate pgmL cmd dynamic pre processor Use cmd as the C pgmP cmd pre processor with cpp dynamic only pgmc cmd Use cmd as the C compiler dynamic Use cmd as the LLVM pgmlo cmd oat dynamic optimiser Use cmd as the LLVM 3 pgmlc cmd i dynamic compiler pgms cmd Use cmd as the splitter dynamic pgma cmd Use cmd as the assembler dynamic pgml cmd Use cmd as the linker dynamic the DLL pgmd11 cmd lcd dynamic generator Use cma as the pgmF cmd pre processor with F dynamic only Use cma as the program for pgmwindres cmd embedding manifests on dynamic Windows Use cmd as the command pgmlibtool cmd for libtool with dynamic staticlib only 4 19 24 Forcing options to particular phases Section 4 12 2 Flag Description Static Dynamic Reverse pass option to the literate y optL option dynamic pre processor E i pass option to cpp with optP option dynamic cpp only 7 f pass option to the custom optF option dynamic pre processor to th optc option pass ae omes dynamic compiler ion to the LLVM a optlo o
288. declaration splice Each declaration group is mutually recursive only within the group Declaration groups can refer to definitions within previous groups but not later ones Accordingly the type environment seen by reify includes all the top level declarations up to the end of the immediately preceding declaration group but no more Concretely consider the following code module M where HWSO 45 6 fx x thl 4 hy k y y S blah1 SAIZ O w z blah2 In this example 1 The body of h would be unable to refer to the function w A reify inside the splice th1 would see the definition of f 2 A reify inside the splice b1ah1 would see the definition of f but would not see the definition of h 3 A reify inside the splice th2 would see the definition of f all the bindings created by th1 and the definition of h 4 A reify inside the splice blah2 would see the same definitions as the splice th2 Compared to the original paper there are many differences of detail The syntax for a declaration splice uses not splice The type of the enclosed expression must be Q Dec not Q Dec Typed expression splices and quotations are supported 7 17 2 Using Template Haskell The data types and monadic constructor functions for Template Haskell are in the library Language Haskell THSyntax You can only run a function at compile time if it is imported from another module That is you can t define a fun
289. dentifier an attempt to quote it as f 7 would be parsed as the character literal followed by the numeric literal 7 There is no current escape mechanism in this unusual situation T has type Name and names the type constructor T That is thing interprets thing in a type context These Names can be used to construct Template Haskell expressions patterns declarations etc They may also be given as an argument to the rei f y function e You may omit the in a top level declaration splice Simply writing an expression rather than a declaration implies a splice For example you can write module Foo where import Bar a Ok deriveStuff f Uses uns Soo TOCAN G y yol deriveStuff g OMES TaS loco Io a gail This abbreviation makes top level declaration slices quieter and less intimidating e Outermost pattern splices may bind variables By outermost here we refer to a pattern splice that occurs outside of any quotation brackets For example WgPere s Bool gt Pac mkPat True pl x y mkPat False fol Gye z 11 SS an another moduler HOO 3 Chae STi gt SCL foo mkPat True x y loge se Sismo Clove gt SEELE bar mkPat False x y e Nested pattern splices do not bind variables By nested here we refer to a pattern splice occurring within a quotation bracket Continuing the example from the last bullet lsaz 8S Bool 0 lago baz b quux
290. documentation for details but a module definition file simply lists what entry points you want to export Here s one that s suitable when building a Haskell COM server DLL EXPORTS D11CanUnloadNow D11CanUnloadNow 0 D11GetClassObject D1ll1GetClassObject 12 DllRegisterServer DllRegisterServer 0 D1llUnregisterServer DllUnregisterServer 0 In addition to creating a DLL the shared option also creates an import library The import library name is derived from the name of the DLL as follows Dis Scola gt aser alos leo His COOle cul al The naming scheme may look a bit weird but it has the purpose of allowing the co existence of import libraries with ordinary static libraries e g 1ibHSfoo a and 1ibHSfoo dll a Additionally when the compiler driver is linking in non static mode it will rewrite occurrence of 1HS foo on the command line to 1HSfoo d11 By doing this for you switching from non static to static linking is simply a question of adding static to your command line The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 312 327 12 6 2 Making DLLs to be called from other languages This section describes how to create DLLs to be called from other languages such as Visual Basic or C This is a special case of Section 8 2 1 2 we ll deal with the DLL specific issues that arise below Here s an example Use foreign export declarations to export the Haskell functions you want t
291. dres which is supplied with a GHC installation See fno embed mani fest in Section 4 12 6 pgmlibtool cmd Use cmd as the libtool command when using staticlib only 4 12 2 Forcing options to a particular phase Options can be forced through to a particular compilation phase using the following flags optL option Pass option to the literate pre processor optP option Pass option to CPP makes sense only if cpp is also on optF option Pass option to the custom pre processor see Section 4 12 4 optc option Pass option to the C compiler optlo option Pass option to the LLVM optimiser optlc option Pass option to the LLVM compiler opta option Pass option to the assembler optl option Pass option to the linker optdl1l option Pass option to the DLL generator optwindres option Pass option to windres when embedding manifests on Windows See fno embed manif est in Section 4 12 6 So for example to force an Ewurb1e option to the assembler you would tell the driver opta Ewurble 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 Section 4 17 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 86 327 4 12 3 Options affecting the C pre processor cpp The C pre processor cpp is run over your Haskell code only if the cpp option is given Unless you a
292. dule A B C in the file src A B C hs with no odir or hidir flags the interface file will be put in src A B C hi and the object file in src A B C o For any module that is imported GHC requires that the name of the module in the import statement exactly matches the name of the module in the interface file or source file found using the strategy specified in Section 4 7 3 This means that for most modules the source file name should match the module name However note that it is reasonable to have a module Main in a file named foo hs but this only works because GHC never needs to search for the interface for module Main because it is never imported It is therefore possible to have several Main modules in separate source files in the same directory and GHC will not get confused In batch compilation mode the name of the object file can also be overridden using the o option and the name of the interface file can be specified directly using the ohi option 4 7 3 The search path In your program you import a module Foo by saying import Foo In make mode or GHCi GHC will look for a source file for Foo and arrange to compile it first Without make GHC will look for the interface file for Foo which should have been created by an earlier compilation of Foo GHC uses the same strategy in each of these cases for finding the appropriate file This strategy is as follows GHC keeps a list of directories called the search path For each
293. e T 6 data T a where Q 8 88 Dot gt Bool gt T Tmt 7 4 8 Generalised Algebraic Data Types GADTs Generalised Algebraic Data Types generalise ordinary algebraic data types by allowing constructors to have richer return types Here is an example data Term a where DLE 6 dime gt SA E SUCE ge Term int gt Term Int IsZero Term Int gt Term Bool TEE Term Bool gt Term a gt Term a gt Term a Pair Term a gt Term o gt Term a b Notice that the return type of the constructors is not always Term a as is the case with ordinary data types This generality allows us to write a well typed eval function for these Terms eval Terma gt a Ewell balie ab i eval Succ t 1 eval t eval IsZero t eval t eval If b el e2 if eval b then eval el els val e2 eval Pair el e2 eval el eval e2 The key point about GADTs is that pattern matching causes type refinement For example in the right hand side of the equation eval Terma gt a eval Lit i the type a is refined to Int That s the whole point A precise specification of the type rules is beyond what this user manual aspires to but the design closely follows that described in the paper Simple unification based type inference for GADTs ICFP 2006 The general principle is this type refinement is only carried out based on user supplied type annotations So if no type signature is supplied for
294. e Data Person hs on Unix Linux Mac or Data Person hs on Windows 4 2 Options overview GHC s behaviour is controlled by options which for historical reasons are also sometimes referred to as command line flags or arguments Options can be specified in three ways The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 45 327 4 2 1 Command line arguments An invocation of GHC takes the following form ghce argument Command line arguments are either options or file names Command line options begin with They may not be grouped vO is different from v O Options need not precede filenames e g ghc x o o foo All options are processed and then applied to all files you cannot for example invoke ghc c 01 Foo hs 02 Bar hs to apply different optimisation levels to the files Foo hs and Bar hs 4 2 2 Command line options in source files Sometimes it is useful to make the connection between a source file and the command line options it requires quite tight For instance if a Haskell source file deliberately uses name shadowing it should be compiled with the fno warn name shad owing option Rather than maintaining the list of per file options in a Makefile it is possible to do this directly in the source file using the OPTIONS_GHC pragma OPTIONS_GHC fno warn name shadowing module X where OPTIONS_GHC is a file header pragma see Section 7 22 Only dynamic flags can be us
295. e however that some architectures trap floating point overflow and loss of precision and report a floating point exception probably terminating the program 13 2 Known bugs or infelicities The bug tracker lists bugs that have been reported in GHC but not yet fixed see the GHC Trac In addition to those GHC also has the following known bugs or infelicities These bugs are more permanent it is unlikely that any of them will be fixed in the short term 13 2 1 Bugs in GHC e GHC can warn about non exhaustive or overlapping patterns see Section 4 8 and usually does so correctly But not always It gets confused by string patterns and by guards and can then emit bogus warnings The entire overlap check code needs an overhaul really e GHC does not allow you to have a data type with a context that mentions type variables that are not data type parameters For example data C a b gt Ta MkT a so that MkT s type is Mier Foro ali als gt a gt E a In principle with a suitable class declaration with a functional dependency it s possible that this type is not ambiguous but GHC nevertheless rejects it The type variables mentioned in the context of the data type declaration must be among the type parameters of the data type e GHC s inliner can be persuaded into non termination using the standard way to encode recursion via a data type The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 318
296. e hsig files will generate normal interface files which other files can also use to type check against However at the moment we always assume that an entity defined in a signature is a unique identifier even though we may happen to know it is type equal with another identifier In the future we will support passing shaping information to the compiler in order to let it know about these type equalities Just like hs boot files when an hsig file is compiled it is checked for type consistency against the backing implementation Signature files are also written in a subset of Haskell essentially identical to that of hs boot files There is one important gotcha with the current implementation currently instances from backing implementations will leak code that uses signatures and explicit instance declarations in signatures are forbidden This behavior will be subject to change 4 7 11 Using 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 SUE E OS lms odie ole os EGool spam Si OBUS Taq ce SC aC ee Ones IS ECO ENS OB weiss Standard suffix rules TOn RIR ASNO S O CS SiC OPTS hs o SE e Hs SHC OTS JON al POOR The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 58 327
297. e An instances for an associated family can only appear as part of an instance declarations of the class in which the family was declared just as with the equations of the methods of a class e The instance for an associated type can be omitted in class instances In that case unless there is a default instance see Section 7 7 3 2 the corresponding instance type is not inhabited i e only diverging expressions such as undefined can assume the type e Although it is unusual there currently can be multiple instances for an associated family in a single instance declaration For example this is legitimate instance GMapKey Flob where data GMap Flob v Gl v data GMap Flob Int G2 Int Here we give two data instance declarations one in which the last parameter is v and one for which it is Int Since you cannot give any subsequent instances for GMap Flob this facility is most useful when the free indexed parameter is of a kind with a finite number of alternatives unlike WARNING this facility may be withdrawn in the future 7 7 3 2 Associated type synonym defaults It is possible for the class defining the associated type to specify a default for associated type instances So for example this is OK class IsBoolMap v where type Key v type instance Key v Int lookupKey Key v gt v gt Maybe Bool instance IsBoolMap Int Bool where lookupKey lookup In an instance declaration for the class if no
298. e already in scope 1 e bound by the enclosing context matters are simple the signature simply constrains the type of the pattern in the obvious way Unlike expression and declaration type signatures pattern type signatures are not implicitly generalised The pattern in a pattern binding may only mention type variables that are already in scope For example e peo iL era el gt a Leis LES o ES where ys a n reverse xs length xs OK vs OB E SS AS ATOK Just vao pos NoE OK Jo abs mor alin SCE Here the pattern signatures for ys and zs are fine but the one for v is not because b is not in scope However in all patterns other than pattern bindings a pattern type signature may mention a type variable that is not in scope in this case the signature brings that type variable into scope This is particularly important for existential data constructors For example data T forall a MkT a ke 2g AP Se a k MkT t a MkT t3 where essgslal le el Here the pattern type signature t a mentions a lexical type variable that is not already in scope Indeed it cannot already be in scope because it is bound by the pattern match GHC s rule is that in this situation and only then a pattern type signature can mention a type variable that is not already in scope the effect is to bring it into scope standing for the existentially bound type variable When a pattern type signature binds a type
299. e and Phant Bool have the same representation even though Age and Bool are unrelated 7 27 2 Role inference What role should a given type parameter should have GHC performs role inference to determine the correct role for every parameter It starts with a few base facts gt has two representational parameters has two nominal parameters all type families parameters are nominal and all GADT like parameters are nominal Then these facts are propagated to all places where these types are used The default role for datatypes and synonyms is phantom the default role for classes is nominal Thus for datatypes and synonyms any parameters unused in the right hand side or used only in other types in phantom positions will be phantom Whenever a parameter is used in a representational position that is used as a type argument to a constructor whose corresponding variable is at role representational we raise its role from phantom to representational Similarly when a The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 277 1327 parameter is used in a nominal position its role is upgraded to nominal We never downgrade a role from nominal to phantom or representational or from representational to phantom In this way we infer the most general role for each parameter Classes have their roles default to nominal to promote coherence of class instances If a C Int were stored in a datatype it would be quit
300. e annotated with interruptible instead of safe or unsafe foreign import ccall interruptible sleep sleepBlock CUint gt IO CUint interruptible behaves exactly as safe except that when a throwTo is directed at a thread in an interruptible foreign call an OS specific mechanism will be used to attempt to cause the foreign call to return Unix systems The thread making the foreign call is sent a SIGPIPE signal using pthread_ki11 This is usually enough to cause a blocking system call to return with EINTR GHC by default installs an empty signal handler for SIGPIPE to override the default behaviour which is to terminate the process immediately Windows systems Vista and later only The RTS calls the Win32 function Cance1SynchronousToO which will cause a blocking I O operation to return with the error ERROR_OPERATION_ABORTED If the system call is successfully interrupted it will return to Haskell whereupon the exception can be raised Be especially careful when using interruptible that the caller of the foreign function is prepared to deal with the consequences of the call being interrupted on Unix it is good practice to check for EINTR always but on Windows it is not typically necessary to handle ERROR_OPERATION_ABORTED 8 1 5 The CAPI calling convention The CApiFFI extension allows a calling convention of capi to be used in foreign declarations e g Torcoroninimpor Weyoal Sad Sr ae ie BR Citic e I
301. e bad if that were somehow changed into a C Age somewhere especially if another C Age had been declared There is one particularly tricky case that should be explained darom Er i eky E lo Misitieialay a 19 What should Tricky s roles be At first blush it would seem that both a and b should be at role representational since both are used in the right hand side and neither is involved in a type family However this would be wrong as the following example shows data Nom a MkNom F a type family F from example above Is Tricky Nom Age representationally equal to Tricky Nom Int No The former stores a Char and the latter stores a Bool The solution to this is to require all parameters to type variables to have role nominal Thus GHC would infer role representational for a but role nominal for b 7 27 3 Role annotations Sometimes the programmer wants to constrain the inference process For example the base library contains the following definition data Ptr a Ptr Addr The idea is that a should really be a representational parameter but role inference assigns it to phantom This makes some level of sense a pointer to an Int really is representationally the same as a pointer to a Bool But that s not at all how we want to use Pt rs So we want to be able to say type role Ptr representational data Ptr a Ptr Addr The type role enabled with XRoleAnnotations declaration forces the parameter a to be at role repr
302. e evaluation only e 39 29 Thesghici fil ula a a O e E a 40 2 10 Compiling to object code inside GHCi 2 2 ee 41 2 11 FAQ and Things To Watch Out For 2 aa 41 3 Using runghe 43 Sil Flass 346 2 4a Sed Pe a ok bea eS BG a eB bak eA ee EE ORE bade es 43 4 Using GHC 44 4 1 Getting started compiling programas 44 4 2 QOpuons OVenvieW 4 ibe S se o SE Bae eed eRe SS AES eee SS 44 42 1 Command line arguments 0 0 0 000 002 ee ee 45 4 2 2 Command line options in source files 2 2 2 ee 45 4 2 3 Setting optionsinGHCi 2 0 0 0 000000 000002 E E ee 45 4 3 Static Dynamic and Mode options 2 2 ee 45 44 Meaninetuliiilesumixes 05 2654 see bea eR eR ea e p ee eee ES oS 46 4 5 Modes of operation ses ee wR ee eR ee 46 4 3 1 sme ghe make ura PR SO ad SE el he Cag ee wa G 47 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 vi 4 6 4 7 4 8 4 9 4 10 4 11 4 5 2 Expression evaluation mode 48 453 Batch compilermode ice ci a A been eer ee 5 48 4 5 3 1 Overriding the default behaviour fora file o 48 Verbosity OPLOS ss new eee ae a e A a ee 49 Filenames and separate compilation ooa 50 ATL Haskell source files 24 4 00 era da a EY we wR EY e 50 4 7 2 Outp t files occasion e A A eee 50 4 7 3 The sSearchipath sora ek Se ee Se a TR ee ee we wo SI 4 7 4 Redirecting the compilation o
303. e expressions 7 3 22 Record field disambiguation In record construction and record pattern matching it is entirely unambiguous which field is referred to even if there are two different data types in scope with a common field name For example module M where clara MES 1 x xg Dame Y ES BOOL module Foo where import M clama I MET 4 se 98 Tame okl MkS x n n l Unambiguous ok2 n MkT x n 1 Unambiguous Ia el Na ss Ambiguous bad2 k x k Ambiguous Even though there are two x s in scope it is clear that the x in the pattern in the definition of ok1 can only mean the field x from type S Similarly for the function ok2 However in the record update in bad1 and the record selection in bad2 it is not clear which of the two types is intended Haskell 98 regards all four as ambiguous but with the XDisambiguateRecordFields flag GHC will accept the former two The rules are precisely the same as those for instance declarations in Haskell 98 where the method names on the left hand side of the method bindings in an instance declaration refer unambiguously to the method of that class provided they are in scope at all even if there are other variables in scope with the same name This reduces the clutter of qualified names when you import two records from different modules that use the same field name Some details e Field disambiguation can be combined with punning see Section 7 3 23 For example
304. e family Inspect x type instance Inspect Age Int type instance Inspect Int Bool class BadIdea a where bad ay o Inspecera The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 276 327 instance BadIdea Int where bad gt 0 deriving instance BadIdea Ag not allowed If the derived instance were allowed what would the type of its method bad be It would seem to be Age gt Inspect Age which is equivalent to Age gt Int according to the type family Inspect Yet if we simply adapt the implementation from the instance for Int the implementation for bad produces a Bool and we have trouble The way to identify such situations is to have roles assigned to type variables of datatypes classes and type synonyms Roles as implemented in GHC are a from a simplified version of the work described in Generative type abstraction and type level computation published at POPL 2011 7 27 1 Nominal Representational and Phantom The goal of the roles system is to track when two types have the same underlying representation In the example above Age and Int have the same representation But the corresponding instances of BadIdea would not have the same representation because the types of the implementations of bad would be different Suppose we have two uses of a type constructor each applied to the same parameters except for one difference For example T Age Bool candT Int Bool c for some type T
305. e help but the rule is this For a lambda bound or case bound variable x either the programmer provides an explicit polymorphic type for x or GHC s type inference will assume that x s type has no foralls in it What does it mean to provide an explicit type for x You can do that by giving a type signature for x directly using a pattern type signature Section 7 13 8 thus NN Eo MI ar eme O AN Alternatively you can give a type signature to the enclosing context which GHC can push down to find the type for the variable NS e Veny ps E A cer asal soll Chiri Here the type signature on the expression can be pushed inwards to give a type signature for f Similarly and more commonly one can give a type signature for the function itself h se forall a a gt a4a gt Bool Char in Ge Ge Tete ac el You don t need to give a type signature if the lambda bound variable is a constructor argument Here is an example we saw earlier too T a gt a gt a Char MTL ow ik oe ie ka we Ta Here we do not need to give a type signature to w because it is an argument of constructor T1 and that tells GHC all it needs to know 7 13 6 3 Implicit quantification GHC performs implicit quantification as follows At the top level only of user written types if and only if there is no explicit forall GHC finds all the type variables mentioned in the type that are not already in scope and universa
306. e in Section 8 2 1 1 except that the aim is not to link a complete program but to make a library from Haskell code that can be deployed in the same way that you would deploy a library of C code The main requirement here is that the runtime needs to be initialized before any Haskell code can be called so your library should provide initialisation and deinitialisation entry points implemented in C or C For example include lt stdlib h gt include HsFFI h HsBool mylib_init void ime arce 2p charikka rgy RAS A a NU char x pargv argv The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 293 327 Initialize Haskell runtime hs_init 8argc pargv do any other initialization here and return false if there was a problem return HS_BOOL_ TRUE void mylib_end void hs_exit The initialisation routine mylib_init calls hs_init as normal to initialise the Haskell runtime and the corresponding deinitialisation function mylib_end calls hs_exit to shut down the runtime 8 2 2 Using header files C functions are normally declared using prototypes in a C header file Earlier versions of GHC 6 8 3 and earlier included the header file in the C source file generated from the Haskell code and the C compiler could therefore check that the C function being called via the FFI was being called at the right type GHC no longer includes external header files when compi
307. e is the stm library The main features supported are these The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 279 327 e Atomic blocks e Transactional variables e Operations for composing transactions retry and orElse e Data invariants All these features are described in the papers mentioned earlier 7 28 3 Parallel Haskell GHC includes support for running Haskell programs in parallel on symmetric shared memory multi processor SMP By default GHC runs your program on one processor if you want it to run in parallel you must link your program with the threaded and run it with the RTS N option see Section 4 15 The runtime will schedule the running Haskell threads among the available OS threads running as many in parallel as you specified with the N RTS option GHC only supports parallelism on a shared memory multiprocessor Glasgow Parallel Haskell GPH supports running Parallel Haskell programs on both clusters of machines and single multiprocessors GPH is developed and distributed separately from GHC see The GPH Page However the current version of GPH is based on a much older version of GHC 4 06 7 28 4 Annotating pure code for parallelism Ordinary single threaded Haskell programs will not benefit from enabling SMP parallelism alone you must expose parallelism to the compiler One way to do so is forking threads using Concurrent Haskell Section 7 28 1 but the simples
308. e module as the definition of any type or class mentioned in the head of the instance declaration the part after the gt see Section 7 6 3 3 then GHC has to visit that interface file anyway Example module A where instance C a gt D T a where care T e sno The instance declaration is only relevant if the type T is in use and if so GHC will have visited A s interface file to find T s definition The only problem comes when a module contains an instance declaration and GHC has no other reason for visiting the module Example 1 This is a change in behaviour relative to 6 2 and earlier The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 60 327 module Orphan where instance C a gt D T a where class C a where Here neither D nor T is declared in module Orphan We call such modules orphan modules GHC identifies orphan modules and visits the interface file of every orphan module below the module being compiled This is usually wasted work but there is no avoiding it You should therefore do your best to have as few orphan modules as possible Functional dependencies complicate matters Suppose we have module B where instance E T Int where data T Is this an orphan module Apparently not because T is declared in the same module But suppose class E had a functional dependency module Lib where class E x y y gt x where Then in some importing mod
309. e more type reconstruction in order to recover the result type of f But after that we are free to use normally 2 5 8 Limitations e When stopped at a breakpoint if you try to evaluate a variable that is already under evaluation the second evaluation will hang The reason is that GHC knows the variable is under evaluation so the new evaluation just waits for the result before continuing The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 32 327 but of course this isn t going to happen because the first evaluation is stopped at a breakpoint Control C can interrupt the hung evaluation and return to the prompt The most common way this can happen is when you re evaluating a CAF e g main stop at a breakpoint and ask for the value of the CAF at the prompt again Implicit parameters see Section 7 13 4 are only available at the scope of a breakpoint if there is an explicit type signature 2 6 Invoking GHCi GHCi is invoked with the command ghci or ghc interactive One or more modules or filenames can also be specified on the command line this instructs GHCi to load the specified modules or filenames and all the modules they depend on just as if you had said load modules at the GHCi prompt see Section 2 7 For example to start GHCi and load the program whose topmost module is in the file Main hs we could say ghci Main hs Most of the command line options accepted by GHC see Chapt
310. e object In particular constructors are not retainers An object B retains object A if i B is a retainer object and 11 object A can be reached by recursively following pointers starting from object B but not meeting any other retainer objects on the way Each live object is retained by one or more retainer objects collectively called its retainer set or its retainer set or its retainers When retainer profiling is requested by giving the program the hr option a graph is generated which is broken down by retainer set A retainer set is displayed as a set of cost centre stacks because this is usually too large to fit on the profile graph each retainer set is numbered and shown abbreviated on the graph along with its number and the full list of retainer sets is dumped into the file prog prof The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 139 327 Retainer profiling requires multiple passes over the live heap in order to discover the full retainer set for each object which can be quite slow So we set a limit on the maximum size of a retainer set where all retainer sets larger than the maximum retainer set size are replaced by the special set MANY The maximum set size defaults to 8 and can be altered with the R RTS option Rsize Restrict the number of elements in a retainer set to size default 8 5 4 2 1 Hints for using retainer profiling The definition of retainers is designed to refl
311. e of the sad state of most UNIX linkers the order of such options does matter If library foo requires library bar then in general 1 foo should come before 1 bar on the command line There s one other gotcha to bear in mind when using external libraries if the library contains a main function then this will be linked in preference to GHC s own main function eg 1ibf2c and 11b1 have their own main s This is because GHC s main comes from the HSrts library which is normally included after all the other libraries on the linker s command line To force GHC s main to be used in preference to any other main s from external libraries just add the option 1HSrts before any other libraries on the command line c Omits the link step This option can be used with make to avoid the automatic linking that takes place if the program contains a Main module package name If you are using a Haskell package see Section 4 9 don t forget to add the relevant package option when linking the program too it will cause the appropriate libraries to be linked in with the program Forgetting the package option will likely result in several pages of link errors framework name On Darwin OS X iOS only link in the framework name This option corresponds to the framework option for Apple s Linker Please note that frameworks and packages are two different things frameworks don t contain any haskell code Rather the
312. e program with to abort with an error message rtsopts all or just rtsopts Enable all RTS option processing both on the command line and through the GHCRTS environment variable In GHC 6 12 3 and earlier the default was to process all RTS options However since RTS options can be used to write logging data to arbitrary files under the security context of the running program there is a potential security problem For this reason GHC 7 0 1 and later default to rt sops some Note that rt sopts has no effect when used with no hs main see Section 8 2 1 1 for details with rtsopts This option allows you to set the default RTS options at link time For example with rtsopts H128m sets the default heap size to 128MB This will always be the default heap size for this program unless the user overrides it Depending on the setting of the rt sopt s option the user might not have the ability to change RTS options at run time in which case with rtsopts would be the only way to set them Note that with rtsopts has no effect when used with no hs main see Section 8 2 1 1 for details fno gen manifest On Windows GHC normally generates a manifest file when linking a binary The manifest is placed in the file prog exe manifest where prog exe is the name of the executable The manifest file currently serves just one purpose it disables the installer detection in Windows Vista that attempts to elevate privileges for executables wi
313. e quotation has type O Type pl where the is a pattern the quotation has type Q Pat e A typed expression splice is written x where x is an identifier or where the is an arbitrary expression A typed expression splice can occur in place of an expression the spliced expression must have type Q TExp a e A typed expression quotation is written as or el 11 where the is an expression if the expression has type a then the quotation has type O TExp a Values of type TExp a may be converted to values of type Exp using the function unType TExp a gt Exp e A quasi quotation can appear in either a pattern context or an expression context and is also written in Oxford brackets The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 245 327 varid where the is an arbitrary string a full description of the quasi quotation facility is given in Sec tion 7 17 6 e A name can be quoted with either one or two prefix single quotes f has type Name and names the function f Similarly C has type Name and names the data constructor C In general thing interprets thing in an expression context A name whose second character is a single quote sadly cannot be quoted in this way because it will be parsed instead as a quoted character For example if the function is called 7 which is a legal Haskell i
314. e trusted XUnsafe Mark a module as unsafe so that it can t be imported by code compiled with XSafe Also enable the Safe Import extension so that a module can require a dependency to be trusted Module Trusted No e Haskell Language Unrestricted e Imported Modules Under control of module author which ones must be trusted And one general flag fpackage trust When enabled turn on an extra check for a trustworthy module M requiring that the package M resides in is considered trusted for the M to be considered trusted And three warning flags fwarn unsafe Issue a warning if the module being compiled is regarded to be unsafe Should be used to check the safety status of modules when using safe inference fwarn safe Issue a warning if the module being compiled is regarded to be safe Should be used to check the safety status of modules when using safe inference fwarn trustworthy safe Issue a warning if the module being compiled is marked as XTrustworthy but it could instead be marked as XSafe a more informative bound Can be used to detect once a Safe Haskell bound can be improved as dependencies are updated The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 287 327 7 29 7 Safe Compilation GHC includes a variety of flags that allow arbitrary processes to be run at compilation time One such example is the custom pre processor flag Another is the ability of Template Haskell to ex
315. ea 264 722 8 RULES pragma sa 644 255 28 PHS ea hb eee se ene be SH 6 Adee ead So oS 264 722 9 SPECIALIZE pragma 20h ke RE RR ee A oe Ee we a 264 T2291 SPECIALIZE INLINE oec tetee beni eB a eae Ee ew Ae eae a 265 7 22 9 2 SPECIALIZE for imported functions e 266 7 22 9 3 Obsolete SPECIALIZE syntax 2 2 2 2 ee 266 7 22 10 SPECIALIZE instance pragma oaao 266 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 XV 7 23 7 24 7 25 7 26 7 27 7 28 7 29 7 22 11UNPACK pragma s rior AR A eR eee 267 1 22 12 NOUNPACK Praga zesci e o e e A a 267 71 22 13 SOURCE prada pco ome SE a A 267 7 22 14 OVERLAPPING OVERLAPPABLE OVERLAPS and INCOHERENT pragmas 268 Rewrite rules gcse Sed BA te Se ea e bh we OAR Gee he BOR ER we EERE eee i amp 268 PAS AAN 268 723 2 SEMANS A e A S 269 7 23 3 How rules interact with INLINE NOINLINE pragmas e 270 7 23 4 How rules interact with CONLIKE pragmas 200002 2p ee 270 TRN LASETUSI N a rr Soe WAS Re A E a a we ee A x 271 1 23 0 Specialisation i sor ss por ee a ae a a IE a a A eo 21a 7 23 7 Controlling what s going on in rewrite rules e 272 Special built in functions coea e e E a e E E E O EA E E AE 213 Generic Classes orea e e Ea ee 4 A Oe Bae e A o eae 213 Generic programming 4 ee da e e a e ee a ee 273 7 26 1 Deriving representations lt s s s secc ee 273 7 2
316. ead wher Or module Wibble WARNING This is an unstable interface wher When you compile any module that import Wibble GHC will print the specified message The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 261 327 e You can attach a warning to a function class type or data constructor with the following top level declarations EPRECATED f C T Don t use these WARNING unsafePerformIO This is unsafe I hope you know what you re doing When you compile any module that imports and uses any of the specified entities GHC will print the specified message You can only attach to entities declared at top level in the module being compiled and you can only use unqualified names in the list of entities A capitalised name such as T refers to either the type constructor T or the data constructor T or both if both are in scope If both are in scope there is currently no way to specify one without the other c f fixities Section 7 4 3 Warnings and deprecations are not reported for a uses within the defining module b defining a method in a class instance and c uses in an export list The latter reduces spurious complaints within a library in which one module gathers together and re exports the exports of several others You can suppress the warnings with the flag fno warn warnings deprecations 7 22 5 MINIMAL pragma T
317. eatures internally it only exposes an API that can used in a safe manner The use of XTrustworthy by itself marks the module as trusted There is an issue here as XTrustworthy may be used by an arbitrary module and module author To control the use of trustworthy modules it is recommended to use the fpackage trust flag This flag adds an extra requirement to the trust check for trustworthy modules such that for trustworthy modules to be considered trusted and allowed to be used in XSafe compiled code the client C compiling the code must tell GHC that they trust the package the trustworthy module resides in This is essentially a way of for C to say while this package contains trustworthy modules that can be used by untrusted modules compiled with XSafe I trust the author s of this package and trust the modules only expose a safe API The trust of a package can be changed at any time so if a vulnerability found in a package C can declare that package untrusted so that any future compilation against that package would fail For a more detailed overview of this mechanism see Section 7 29 4 In the example Danger can import module RIO because RIO is marked trustworthy Thus Danger can make use of the rioRead File and rioWriteFile functions to access permitted file names The main application then imports both RIO and Danger To run the plugin it calls RIO runRIO Danger runMe within the IO monad The application is safe in the knowledge that the
318. echecker dynamic ddump vt trac Trace vectoriser dynamic ddump rn trac Trace renamer dynamic ddump rn stats Renamer stats dynamic ddump simpl stats Dump simplifier stats dynamic Suppress unsolicited dno debug output debugging output static Turn on debug printing i tat dppr debug more verbose ES t the depth f inti i dppr user length Seite ep o dynamic expressions in error msgs Set the width of debugging dppr colsNNN output For example dynamic dppr cols200 Print single alternative case A dppr case as let 2 dynamic expressions as Strict lets In core dumps suppress thi tf dsuppress all DERA mg fencer ad dynamic uniques that is suppressible Suppress the printing of dsuppress uniques uniques in debug output dynamic easier to use diff Suppress extended ds ress idinfo Aron dynamic TER identifiers where they are y bound dsuppress module Suppress ie penne i module qualification dynamic prefixes prefixes dsuppress type S t t d on tass uppress type signatures ynamic dsuppress type TA A E S t licat d a uppress type applications ynamic the printi f O UEbESSES Suppress he printing o l coercions in Core dumps to dynamic coercions make them shorter dsource stats Dump haskell source stats dynamic dcmm lint C pass sanity checking dynamic dstg lint STG pass sanity checking dynamic dstg stats Dump STG stats dynamic dverbose Show output from each
319. eclaration may not mention variables bound by other declarations That is each declaration must be self contained For example the following program is not allowed let x gt y 1 y gt x e2 in x For some amplification on this design choice see Trac 4061 e Typing If exp has type T1 gt T2 and pat matches a T2 then the whole view pattern matches a T1 e Matching To the equations in Section 3 17 3 of the Haskell 98 Report add the following case v of gt 19 gt il gt e2 case e w ol 9 gt el y gt e2 That is to match a variable v against a pattern exp gt pat evaluate exp v and match the result against pat The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 159 327 e Efficiency When the same view function is applied in multiple branches of a function definition or a case expression e g in size above GHC makes an attempt to collect these applications into a single nested case expression so that the view function 1s only applied once Pattern compilation in GHC follows the matrix algorithm described in Chapter 4 of The Implementation of Functional Programming Languages When the top rows of the first column of a matrix are all view patterns with the same expression these patterns are transformed into a single nested case This includes for example adjacent view patterns that line up in a tuple as in f view gt A pl p2
320. ect a common cause of space leaks a large structure is retained by an unevaluated computation and will be released once the computation is forced A good example is looking up a value in a finite map where unless the lookup is forced in a timely manner the unevaluated lookup will cause the whole mapping to be retained These kind of space leaks can often be eliminated by forcing the relevant computations to be performed eagerly using seq or strictness annotations on data constructor fields Often a particular data structure is being retained by a chain of unevaluated closures only the nearest of which will be reported by retainer profiling for example A retains B B retains C and C retains a large structure There might be a large number of Bs but only a single A so A is really the one we re interested in eliminating However retainer profiling will in this case report B as the retainer of the large structure To move further up the chain of retainers we can ask for another retainer profile but this time restrict the profile to B objects so we get a profile of the retainers of B LEO RINS m2 NGE This trick isn t foolproof because there might be other B closures in the heap which aren t the retainers we are interested in but we ve found this to be a useful technique in most cases 5 4 3 Biographical Profiling A typical heap object may be in one of the following four states at each point in its lifetime e The lag stage which i
321. ecute Haskell code at compilation time including IO actions Safe Haskell does not address this danger although Template Haskell is a disallowed feature Due to this it is suggested that when compiling untrusted source code that has had no manual inspection done the following precautions be taken e Compile in a sandbox such as a chroot or similar container technology Or simply as a user with very reduced system access e Compile untrusted code with the XSafe flag being specified on the command line This will ensure that modifications to the source being compiled can t disable the use of the Safe Language as the command line flag takes precedence over a source level pragma e Ensure that all untrusted code is imported as a safe import and that the fpackage trust flag is used with packages from untrusted sources being marked as untrusted There is a more detailed discussion of the issues involved in compilation safety and some potential solutions on the GHC Wiki The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 288 327 Chapter 8 Foreign function interface FFI GHC mostly conforms to the Haskell Foreign Function Interface whose definition is part of the Haskell Report on http www haskell org FFI support is enabled by default but can be enabled or disabled explicitly with the XForeignFunctionInterface flag GHC implements a number of GHC specific extensions to the FFI Addendum These e
322. ed in an OPTIONS_GHC pragma see Section 4 3 Note that your command shell does not get to the source file options they are just included literally in the array of command line arguments the compiler maintains internally so you ll be desperately disappointed if you try to glob etc inside OPTIONS_GHC NOTE the contents of OPTIONS_GHC are appended to the command line options so options given in the source file override those given on the command line It is not recommended to move all the contents of your Makefiles into your source files but in some circumstances the OPTION S_GHC pragma is the Right Thing If you use keep hc file and have OPTION flags in your module the OPTIONS_GHC will get put into the generated hc file 4 2 3 Setting options in GHCi Options may also be modified from within GHCi using the set command See Section 2 8 for more details 4 3 Static Dynamic and Mode options Each of GHC s command line options is classified as static dynamic or mode Mode flags For example make or E There may only be a single mode flag on the command line The available modes are listed in Section 4 5 Dynamic Flags Most non mode flags fall into this category A dynamic flag may be used on the command line in a OPTIONS _GHC pragma in a source file or set using set in GHCi Static Flags A few flags are static which means they can only be used on the command line and remain in force over the entire GHC G
323. ed type in a top level binding e You cannot bind a variable with an unboxed type in a recursive binding e You may bind unboxed variables in a non recursive non top level pattern binding but you must make any such pattern match strict For example rather than data Foo Foo Int Int oe ler ROO 2 Jo 10 oo Bas dim ces you must write The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 154 327 data Foo Foo Int Int SRC O OA SO since b has type Int 7 2 2 Unboxed tuples Unboxed tuples aren t really exported by GHC Ext s they are a syntactic extension enabled by the language flag XUnboxed Tuples An unboxed tuple looks like this A EA where e_1 e_n are expressions of any type primitive or non primitive The type of an unboxed tuple looks the same Note that when unboxed tuples are enabled is a single lexeme so for example when using operators like and you need to write and rather than and Unboxed tuples are used for functions that need to return multiple values but they avoid the heap allocation normally associated with using fully fledged tuples When an unboxed tuple is returned the components are put directly into registers or on the stack the unboxed tuple itself does not have a composite representation Many of the primitive operations listed in primops txt pp return unboxed tuples In particular the TO a
324. eee ee ee ae ee Se be ee ee 9 L34 Known DUSS lt eea oeae a a A ess de 9 1 6 Release notes for version 7 102 9 LOI GHG iia a MS OR ga BI GOR ad Aa es 9 1 6 2 Libran s oo oe cedeo e e e Ad a A aba awe 10 W621 DASS rr e A A a eS 10 1622 DINA e tr A RI A AS See Bd a ns Se 10 16 23 Cabaliuoogiarars p a epe a beh ee bb ded behead Eee Ga ewe eo 10 WO24 AN 11 1 6 3 Known DUZS concisa oa ee ee OS a ee ea ea wt a a E 11 2 Using GHCi 12 2 1 Introduction te GHCI sc es ORI OR e A OE a CAE EEO eee eG 12 2 2 Loading source files so se me ed i we Bae de O ea e he RR ae eS E amp 12 2 2 1 Modules vs filenames 2 2 teapa ea ee 13 2 2 2 Making changes and recompilation 2 0 0 0 eee ee 13 2 3 Loading compiled code s sos s e sess ae Re a eae Pa ee Re ew ee ae eee 14 2 4 Interactive evaluation atthe prompt 2 2 2 0 000020 ee ee 15 2 4 1 TO actions at the prompt 5 2 4 2 Using do notation atthe prompt 16 24 3 Multthnesnput ss Ae Lat hte Bie Eee Bi ie A eee ee we EE Sas Be eee eared oo 17 2 4 4 Type class and other declarations ee 18 2 4 5 What s really in scope atthe prompt oaoa ee ee 19 2 4 5 1 The effect of Load on what is in scope e 19 2 4 5 2 Controlling what is in scope with import e 20 2 4 5 3 Controlling what is in scope with the module command 20 2 4 5 4 Qualified names 0 ee 21 245 9 smoduleand Lodi Ga ie
325. ehave uniformly with all other forms of pattern matching For example let Use IA e ha la 1s equivalent to this lert I case amp or 6 1 gt lt Sean 16 A FSL E y emel ic al a ig The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 257 327 The binding is lazy but when either x or y is evaluated by b the entire pattern is matched including forcing the evaluation of x Bang patterns work in case expressions too of course g5 x let y fx in body g6 x CES E SX D ff y gt lose TUE ES AS CO E gt Dochy The functions g5 and g6 mean exactly the same thing But g7 evaluates f x binds y to the result and then evaluates body 7 19 2 Syntax and semantics We add a single new production to the syntax of patterns PAra There is one problem with syntactic ambiguity Consider Is this a definition of the infix function or of the f with a bang pattern GHC resolves this ambiguity in favour of the latter If you want to define with bang patterns enabled you have to do so using prefix notation 1 x 3 The semantics of Haskell pattern matching is described in Section 3 17 2 of the Haskell Report To this description add one extra item 10 saying e Matching the pattern pat against a value v behaves as follows if v is bottom the match diverges otherwise pat is matched against v Similarly in Figure 4 of Section 3 17 3 add a new case
326. eies SE I 88 he S gt 2 gt The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 218 327 The recursive use of T forced the second argument to have kind x However just as in type inference you can achieve polymor phic recursion by giving a complete kind signature for T A complete kind signature is present when all argument kinds and the result kind are known without any need for inference For example Bat aol Ci SR e gt AI ae INS MUS SS me 11 Meyos ua gt 1 me The complete user supplied kind signature specifies the polymorphic kind for T and this signature is used for all the calls to T including the recursive ones In particular the recursive use of T is at kind What exactly is considered to be a complete user supplied kind signature for a type constructor These are the forms e For a datatype every type variable must be annotated with a kind In a GAD Estyle declaration there may also be a kind signature with a top level in the header but the presence or absence of this annotation does not affect whether or not the declaration has a complete signature data T is e cso Pere ene where A O ke al oe ere ie a daca T2 er 8S de Sse ay Be Te gs where Mes MZ 98 Orali k Us gt k gt s circa Us a 32 gt 6 Co 98 Ke 98 5 waste 030 MES Pa 32 Formal keo kes gt le gt y Glace M a e ke gt E Uo 39 e where es ODA es Torei le
327. eloped When loading up source modules with load GHCi normally looks for any corresponding compiled object files and will use one in preference to interpreting the source if possible For example suppose we have a 4 module program consisting of modules A B C and D Modules B and C both import D only and A imports both B amp C A AN B Vd D We can compile D then load the whole program like this Prelude gt ghc c dynamic D hs Prelude gt load A Compiling B B hs interpreted Compiling C C hs interpreted Compiling A A hs interpreted Ok modules loaded A B C D Main gt In the messages from the compiler we see that there is no line for D This is because it isn t necessary to compile D because the source and everything it depends on is unchanged since the last compilation Note the dynamic flag to GHC GHCi uses dynamically linked object code if you are on a platform that supports it and so in order to use compiled code with GHCi it must be compiled for dynamic linking At any time you can use the command show modules to get a list of the modules currently loaded into GHCi Main gt show modules D CNG eis Teli C C hs interpreted B B hs interpreted A A hs interpreted Main gt If we now modify the source of D or pretend to using the Unix command touch on the source file is handy for this the compiler will no longer be able to use the object file because it
328. elp where class My myshow instance myshow showHelp showHelp Al LANGUAGE module Main import data T instance myshow instance myshow main d In function sho call to myshow in main GHC resolves the MyShow Show a where a gt Sicweilmg a where concatMap myshow xs MyShow a gt MyShow XS MyShow a gt a myshow xs ES XS FlexibleInstances OverlappingInstances where elp kT yShow T where x Used generic instance yShow T where xs Used more specific instance o print myshow MkT print showHelp MkT wHelp GHC sees no overlapping instances and so uses the MyShow a instance without complaint In the T constraint using the overlapping instance declaration in module Main As a result the program prints Used more specific instance Used generic instance An alternative possible behaviour not currently implemented would be to reject module Help on the grounds that a later instance declaration might overlap the local one 7 6 3 6 Instance signatures type signatures in instance declarations In Haskell you can t write a type signature in an instance declaration but it is sometimes convenient to do so and the language extension XInstanceSigs allows you to do so For example data Ta MkT aa instance Eq a gt Eq T a where Tar Da es ROO The signature MkT x1 x2 MkTy yl y2 xl yl amp amp x2 y2
329. ely and has the effect of disabling timers that depend on it the context switch timer and the heap profiling timer Context switches will still happen but deterministically and at a rate much faster than normal Disabling the interval timer is useful for debugging because it eliminates a source of non determinism at runtime install signal handlers yes no If yes the default the RTS installs signal handlers to catch things like ctrl C This option is primarily useful for when you are using the Haskell code as a DLL and want to set your own signal handlers Note that even with install signal handlers no the RTS interval timer signal is still enabled The timer signal is either SIGVTALRM or SIGALRM depending on the RTS configuration and OS capabilities To disable the timer signal use the V0 RTS option see above xmaddress WARNING this option is for working around memory allocation problems only Do not use unless GHCi fails with a message like failed to mmap memory below 2Gb If you need to use this option to get GHCi working on your machine please file a bug On 64 bit machines the RTS needs to allocate memory in the low 2Gb of the address space Support for this across different operating systems is patchy and sometimes fails This option is there to give the RTS a hint about where it should be able to allocate memory in the low 2Gb of the address space For example RTS xm20000000 RTS would hint that the RTS sh
330. empty Text empty Text tosrringik MEA gt Sieg toString Text s s module A where import Text z toString empty Presently module A depends explicitly on a concrete implementation of Text What if we wanted to a signature Text so we could vary the implementation with other possibilities e g packed UTF 8 encoded bytestrings To do this we can write a signature Text Sig hsig and modify A to include the signature instead The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 57 327 module TextSig where data Text empEy 2 TEE LOST BY Text gt SELME module A where import TextSig z toString empty To compile these two files we need to specify what module we would like to use to implement the signature This can be done by compiling the implementation and then using the sig of flag to specify the implementation backing a signature ghe c Text hs e a Lextsi Gahisig So Om ae Mega a e A NS Signature files can also be compiled as part of make in which case the syntax is extended to support specifying implemen tations of multiple signatures as FooSig is main Foo BarSig is main Bar At the moment you must specify the full module name package key colon and then module name although in the future we may support more user friendly syntax To just type check an interface file no sig of is necessary instead just pass the options fno cod fwrite int rfac
331. ence barrier try out this skeletal worked example First cut and paste the two modules below into Main hs and Printf hs Melo hs module Main where Import our template pr aioe Primei jose The splice operator takes the Haskell source code generated at compile time by pr and splices it into the argument of putStrLn main putStrIn pr Hello REI ns module Printf where Skeletal printf from the paper It needs to be in a separate module to the one wher you intend to use it Import some Template Haskell syntax import Language Haskell TH The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 248 327 Describe a format string data Format D S L String T Parse a format string This is left largely to you as we are here interested in building our first ever Template Haskell program and not in building printf parse String gt Format parse s Ee Generate Haskell source code from a parsed representation of the format string This code will be spliced into the module which calls pr at compile time gen Format gt Exp gen D An gt show n gen S e gt s Jl gen L s SENGES Here we generate the Haskell code for the splice EON c a mole OANE SEELE joie 8 errie gt Q 11299 pr s gen parse s Now run the compiler here we are a Cygwin prompt on
332. endencies The easiest way to do this is to use cabal instal1l or download the packages from HackageDB and build and install them as normal Be careful not to recompile any packages that GHC itself depends on as this may render the ghc package itself broken and ghc cannot be simply recompiled The only way to recover from this would be to re install GHC The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 72 327 4 9 7 Package management the ghc pkg command The ghc pkg tool is for querying and modifying package databases To see what package databases are in use use ghc pkg list The stack of databases that ghc pkg knows about can be modified using the GHC_PACKAGE_ PATH environment variable see Section 4 9 5 1 and using package db options on the ghc pkg command line When asked to modify a database ghc pkg modifies the global database by default Specifying user causes it to act on the user database or package db can be used to act on another database entirely When multiple of these options are given the rightmost one is used as the database to act upon Commands that query the package database list latest describe field dot operate on the list of databases specified by the flags user global and package db If none of these flags are given the default is global user If the environment variable GHC_PACKAGE_PATH is set and its value does not end in a separator
333. enerating 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 The command ghc M will append the needed dependencies to your Makefile In general ghc M Foo does the following For each module M in the set Foo plus all its imports transitively it adds to the Makefile e A line recording the dependence of the object file on the source file MoOR EMANS or M 1hs if that is the filename you used e For each import declaration import X in M a line recording the dependence of M on X MSC Xin M a line recording the dependence of M on X EJ e For each import declaration import SOURCI Mone xe boots The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 59 327 See Section 4 7 9 for details of hi boot style interface files If M imports multiple modules then there will be multiple lines with M o as the target There is no need to list all of the source files as arguments to the ghc M command ghc traces the dependencies just like ghe make a new feature in GHC 6 4 Note that ghc M needs to find a source file for each module in the dependency graph so that it can parse the import declarations and follow dependencies Any pre compiled modules without source files must therefore belong to a pa
334. ep is incoherent the search succeeds returning that candidate e If not find all instances that unify with the target constraint but do not match it Such non candidate instances might match when the target constraint is further instantiated If all of them are incoherent the search succeeds returning the selected candidate if not the search fails Notice that these rules are not influenced by flag settings in the client module where the instances are used These rules make it possible for a library author to design a library that relies on overlapping instances without the client having to know Errors are reported lazily when attempting to solve a constraint rather than eagerly when the instances themselves are defined Consider for example The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 202 327 instance C Int b where instance C a Bool where These potentially overlap but GHC will not complain about the instance declarations themselves regardless of flag settings If we later try to solve the constraint C Int Char then only the first instance matches and all is well Similarly with C Bool Bool Butif we try to solve C Int Bool both instances match and an error is reported As a more substantial example of the rules in action consider instance OVERLAPPABLE contextl gt C Int b where A instance OVERLAPPABLE context2 gt Ca Bool where
335. er 10 for information about crashes space leaks and other undesirable phenomena The limitations here are listed in Haskell Report order roughly 13 1 1 Divergence from Haskell 98 and Haskell 2010 By default GHC mainly aims to behave mostly like a Haskell 2010 compiler although you can tell it to try to behave like a particular version of the language with the KHaske1198 and XHaske112010 flags The known deviations from the standards are described below Unless otherwise stated the deviation applies in Haskell 98 Haskell 2010 and the default modes 13 1 1 1 Lexical syntax e Certain lexical rules regarding qualified identifiers are slightly different in GHC compared to the Haskell report When you have module reservedop such as M GHC will interpret it as a single qualified operator rather than the two lexemes M and 13 1 1 2 Context free syntax e In Haskell 98 mode and by default but not in Haskell 2010 mode GHC is a little less strict about the layout rule when used in do expressions Specifically the restriction that a nested context must be indented further to the right than the enclosing context is relaxed to allow the nested context to be at the same level as the enclosing context if the enclosing context is a do expression For example the following code is accepted by GHC main do args lt getArgs if null args then return else do ps lt mapM process args mapM print ps This behaviour is contro
336. er 4 also make sense in interactive mode The ones that don t make sense are mostly obvious 2 6 1 Packages Most packages see Section 4 9 1 are available without needing to specify any extra flags at all they will be automatically loaded the first time they are needed For hidden packages however you need to request the package be loaded by using the package flag ghci package readline GHCi version 6 8 1 http www haskell org ghc for help Loading package base linking done Loading package readline 1 0 linking done Prelude gt The following command works to load new packages into a running GHCi Prelude gt set package nam But note that doing this will cause all currently loaded modules to be unloaded and you ll be dumped back into the Prelude 2 6 2 Extra libraries Extra libraries may be specified on the command line using the normal 11ib option The term library here refers to libraries of foreign object code for using libraries of Haskell source code see Section 2 2 1 For example to load the m library ghei Im On systems with so style shared libraries the actual library loaded will the 1ibiib so GHCi searches the following places for libraries in this order e Paths specified using the Lpath command line option e the standard library search path for your system which on some systems may be overridden by setting the LD_LIBRARY_P ATH environment variable
337. er of the library would have to explicitly use Safe Haskell which is an unreasonable expectation of the whole Haskell community Or the user of the library would have to wrap it in a shim that simply re exported your API through a trustworthy module an annoying practice 7 29 6 Safe Haskell Flag Summary In summary Safe Haskell consists of the following three language flags XSafe To be trusted all of the module s direct imports must be trusted but the module itself need not reside in a trusted package because the compiler vouches for its trustworthiness The safe keyword is allowed but meaningless in import statements every import is required to be safe regardless e Module Trusted Yes e Haskell Language Restricted to Safe Language e Imported Modules All forced to be safe imports all must be trusted XTrustworthy This establishes that the module is trusted but the guarantee is provided by the module s author A client of this module then specifies that they trust the module author by specifying they trust the package containing the module XTrustworthy has no effect on the accepted range of Haskell programs or their semantics except that they allow the safe import keyword e Module Trusted Yes e Module Trusted fpackage trust enabled Yes but only if the package the module resides in is also trusted e Haskell Language Unrestricted e Imported Modules Under control of module author which ones must b
338. er s Guide Version 7 10 2 292 327 ineluce Mica la endif int main int argc char xargv ime Lp if _ GLASGOW_HASKELL_ gt 703 RtsConfig conf defaultRtsConfig conf rts_opts_enabled RtsOptsAll ING imit cla Maneja ELE SOME y y else hs_init 8argc amp argv endif ore al 0p a lt 5p iH 4 princi Veen sere 2500 Ye hs_exit return 0 Note two changes we included Rt s h which defines the GHC specific external RTS interface and we called hs_init_gh c instead of hs_init passing an argument of type Rt sConfig RtsConfig is a struct with various fields that affect the behaviour of the runtime system Its definition is typedef struct RtsOptsEnabledEnum rts_opts_enabled const Chat Pls opts ets Song extern const RtsConfig defaultRtsConfig typedef enum RtsOptsNone RTS causes an error RtsOptsSafeOnly safe RTS options allowed others cause an error RtsOptsAll all RTS options allowed RtsOptsEnabledEnum There is a default value defaultRtsConfig that should be used to initialise variables of type Rt sConfig More fields will undoubtedly be added to Rt sConfig in the future so in order to keep your code forwards compatible it is best to initialise with defaultRtsConfig and then modify the required fields as in the code sample above 8 2 1 2 Making a Haskell library that can be called from foreign code The scenario here is much lik
339. erns are enabled by the flag KViewPatterns More information and examples of view patterns can be found on the Wiki page View patterns are somewhat like pattern guards that can be nested inside of other patterns They are a convenient way of pattern matching against values of abstract types For example in a programming language implementation we might represent the syntax of the types of the language as follows type Typ data TypView Unit Arrow Typ Typ view Typ gt TypView additional operations for constructing Typ s The representation of Typ is held abstract permitting implementations to use a fancy representation e g hash consing to manage sharing Without view patterns using this signature a little inconvenient The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 158 327 size ES Iyp gt Integer size t case view t of Umie il aro jedl je eee S E It is necessary to iterate the case rather than using an equational function definition And the situation is even worse when the matching against t is buried deep inside another pattern View patterns permit calling the view function inside the pattern and matching against the result size view gt Unit 1 size view gt Arrow tl t2 size tl size t2 That is we add a new form of pattern written expression gt pattern that means apply the expression to whatever we re trying to match against and then m
340. errors are deferred to runtime Type errors will still be emitted as warnings but will not prevent compilation This flag implies the fdefer typed holes flag which enables this behaviour for typed holes Should you so wish it is possible to enable fdefer typ rrors without enabling fdefer typed holes by explicitly specifying fno defer typed holes on the commandline after the fdefer typ rrors flag At runtime whenever a term containing a type error would need to be evaluated the error is converted into a runtime exception Note that type errors are deferred as much as possible during runtime but invalid coercions are never performed even when they would ultimately result in a value of the correct type For example given the following code 6 88 Alive x 0 Y 58 Char y Xx wa EE aka E evaluating z will result in a runtime type error 7 16 2 Deferred type errors in GHCi The flag fdefer typ rrors works in GHCi as well with one exception for naked expressions typed at the prompt type errors don t get delayed so for example Prelude gt fst True 1 PE lt interactive gt 2 12 No instance for Num Char arising from the literal 1 Possible fix add an instance declaration for Num Char In the first argument of namely 1 In the expression a In the first argument of fst namely True 1 a Otherwise in the common case of a simple t
341. ers in source code which are persisted when compiled These pieces of data can then inspected and utilized when using GHC as a library or writing a compiler plugin 9 1 1 Annotating values Any expression that has both Typeable and Data instances may be attached to a top level value binding using an ANN pragma In particular this means you can use ANN to annotate data constructors e g Just as well as normal values e g take By way of example to annotate the function foo with the annotation Just Hello you would do this ANN foo Just Hello HOO 006 A number of restrictions apply to use of annotations The binder being annotated must be at the top level i e no nested binders The binder being annotated must be declared in the current module The expression you are annotating with must have a type with Typeable and Data instances The Template Haskell staging restrictions apply to the expression being annotated with so for example you cannot run a function from the module being compiled To be precise the annotation ANN x e is well staged if and only if e would be disregarding the usual type restrictions of the splice syntax and the usual restriction on splicing inside a splice 1 is fine as an annotation albeit redundant If you feel strongly that any of these restrictions are too onerous please give the GHC team a shout However apart from these restrictions many things are allowed i
342. ers too isAlpha The Haskell 98 definition of isAlpha is isAlpha c isUpper c isLower c GHC s implementation diverges from the Haskell 98 definition in the sense that Unicode alphabetic characters which are neither upper nor lower case will still be identified as alphabetic by isAlpha hGetContents Lazy I O throws an exception if an error is encountered in contrast to the Haskell 98 spec which requires that errors are discarded see Section 21 2 2 of the Haskell 98 report The exception thrown is the usual IO exception that would be thrown if the failing IO operation was performed in the IO monad and can be caught by System 10 Error catch or Control Exception catch 13 1 1 8 The Foreign Function Interface hs_init not allowed after hs_exit The FFI spec requires the implementation to support re initialising itself after being shut down with hs_exit but GHC does not currently support that The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 317 327 13 1 2 GHC s interpretation of undefined behaviour in Haskell 98 and Haskell 2010 This section documents GHC s take on various issues that are left undefined or implementation specific in Haskell 98 The Char type Following the ISO 10646 standard maxBound Char in GHC is 0x10FFFF Sized integral types In GHC the Int type follows the size of an address on the host architecture in other words it holds 32 bits on a 32 bit machine and
343. ersion The package s version usually in the form A B any number of components are allowed license string The type of license under which this package is distributed This field is a value of the License type license file optional string The name of a file giving detailed license information for this package copyright optional freeform The copyright string maintainer optional freeform The email address of the package s maintainer stability optional freeform A string describing the stability of the package eg stable provisional or experimental homepage optional freeform URL of the package s home page package url optional freeform URL of a downloadable distribution for this package The distribution should be a Cabal package description optional freeform Description of the package category optional freeform Which category the package belongs to This field is for use in conjunction with a future centralised package distribution framework tentatively titled Hackage author optional freeform Author of the package exposed bool Whether the package is exposed or not exposed modules string list modules exposed by this package hidden modules string list modules provided by this package but not exposed to the programmer These modules cannot be imported but they are still subject to the overlapping constraint no other package in the same program may provide a module of the same name reexported modu
344. es any costs memory allocation and time to whatever the current cost centre stack is at the time the cost is incurred The mechanism is simple whenever the program evaluates an expression with an SCC annotation SCC c E the cost centre c is pushed on the current stack and the entry count for this stack is incremented by one The stack also sometimes has to be saved and restored in particular when the program creates a thunk a lazy suspension the current cost centre stack is stored in the thunk and restored when the thunk is evaluated In this way the cost centre stack is independent of the actual evaluation order used by GHC at runtime At a function call GHC takes the stack stored in the function being called which for a top level function will be empty and appends it to the current stack ignoring any prefix that is identical to a prefix of the current stack We mentioned earlier that lazy computations i e thunks capture the current stack when they are created and restore this stack when they are evaluated What about top level thunks They are created when the program is compiled so what stack should we give them The technical name for a top level thunk is a CAF Constant Applicative Form GHC assigns every CAF in a module a stack consisting of the single cost centre M CAF where M is the name of the module It is also possible to give each CAF a different stack using the option fprof cafs This is especially use
345. es match too See Section 7 23 6 below GHC keeps trying to apply the rules as it optimises the program For example consider The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 270 327 let s map f E map g in s t xs The expression s t xs does not match the rule map map but GHC will substitute for s and t giving an expression which does match If s or t was a used more than once and b large or a redex then it would not be substituted and the rule would not fire 7 23 3 How rules interact with INLINE NOINLINE pragmas Ordinary inlining happens at the same time as rule rewriting which may lead to unexpected results Consider this artificial example EZ gyn y h z g True RULES f True False Since f s right hand side is small it is inlined into g to give Say SY Now g is inlined into h but s RULE has no chance to fire If instead GHC had first inlined g into h then there would have been a better chance that s RULE might fire The way to get predictable behaviour is to use a NOINLINE pragma or an INLINE phase pragma on f to ensure that it is not inlined until its RULEs have had a chance to fire The warning flag fwarn inline rule shadowing see Section 4 8 warns about this situation 7 23 4 How rules interact with CONLIKE pragmas GHC is very cautious about duplicating work For example consider f k z xs let xs build gy Ay go
346. escribed in the paper Type Checking with Open Type Functions T Schrijvers S Peyton Jones M Chakravarty and M Sulzmann in Proceedings of ICFP 2008 The 13th ACM SIGPLAN International Conference on Functional Programming ACM Press pages 51 62 2008 Type families essentially provide type indexed data types and named functions on types which are useful for generic programming and highly parameterised library interfaces as well as interfaces with enhanced static information much like dependent types They might also be regarded as an alternative to functional dependencies but provide a more functional style of type level programming than the relational style of functional dependencies Indexed type families or type families for short are type constructors that represent sets of types Set members are denoted by supplying the type family constructor with type parameters which are called type indices The difference between vanilla parametrised type constructors and family constructors is much like between parametrically polymorphic functions and ad hoc polymorphic methods of type classes Parametric polymorphic functions behave the same at all type instances whereas class methods can change their behaviour in dependence on the class type parameters Similarly vanilla type constructors imply the same data representation for all type instances but family constructors can have varying representation types for varying type indices I
347. esent any collection whose elements have a hash function Omitting standard implementation details this would lead to the following declarations instance Eq gt Collects e wher instance Eq gt Collects gt Bool where instance Collects Char BitSet where instance Hashable e Collects a ce gt Collects e Array Int ce where All this looks quite promising we have a class and a range of interesting implementations Unfortunately there are some serious problems with the class declaration First the empty function has an ambiguous type empty Collects ce gt c By ambiguous we mean that there is a type variable e that appears on the left of the gt symbol but not on the right The problem with this is that according to the theoretical foundations of Haskell overloading we cannot guarantee a well defined semantics for any term with an ambiguous type We can sidestep this specific problem by removing the empty member from the class declaration However although the remain ing members insert and member do not have ambiguous types we still run into problems when we try to use them For example consider the following two functions x y insert x insert y g f True a for which GHC infers the following types E ES Collects a Collects e o o G oS e G sg COLES CESE O O LEO MESE ES Cheas C 7 G The Glorious Glasgow Haskell Compilation System User s Guide Version
348. esentational not role phantom GHC then checks the user supplied roles to make sure they don t break any promises It would be bad for example if the user could make BadIdea s role be representational As another example we can consider a type Set a that represents a set of data ordered according to a s Ord instance While it would generally be type safe to consider a to be at role representational it is possible that a newt ype and its base type have different orderings encoded in their respective Ord instances This would lead to misbehavior at runtime So the author of the Set datatype would like its parameter to be at role nominal This would be done with a declaration type role Set nominal Role annotations can also be used should a programmer wish to write a class with a representational or phantom role However as a class with non nominal roles can quickly lead to class instance incoherence it is necessary to also specify KIncoheren t Instances to allow non nominal roles for classes The other place where role annotations may be necessary are in hs boot files Section 4 7 9 where the right hand sides of definitions can be omitted As usual the types classes declared in an hs boot file must match up with the definitions in the hs file including down to the roles The default role for datatypes is representational in hs boot files corresponding to the common use case Role annotations are allowed on data newtype and
349. ess where Nil Vec Zero a Coims 223 a E CAS WEE SuGe im 2 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 65 327 Will raise two warnings because Zero and Succ are not written as Zero and Succ This warning is enabled by default in Wal1 mode fwarn unused binds Report any function definitions and local bindings which are unused More precisely e Warn if a binding brings into scope a variable that is not used except if the variable s name starts with an underscore The starts with underscore condition provides a way to selectively disable the warning A variable is regarded as used if It is exported or It appears in the right hand side of a binding that binds at least one used variable that is used For example module A f where f let p q rhsl int p Warning about unused q t rhs3 No warning f is used and hence so is t g hx Warning g unused h rhs2 Warning h is only used in the right hand side of another unused binding w True No warning _w starts with an underscore e Warn if a pattern binding binds no variables at all unless it is a lone possibly banged wild card pattern For example Just _ rhs3 Warning unused pattern binding 7 tas Warning unused pattern binding hiss No warning lone wild card pattern _ rhs4 No warning banged wild card pattern behaves like seq The motivation
350. et the best of both worlds fast pre compiled library code and fast compile turnaround for the parts of your program being actively developed GHC supports numerous language extensions including concurrency a foreign function interface exceptions type system ex tensions such as multi parameter type classes local universal and existential quantification functional dependencies scoped type variables and explicit unboxed types These are all described in Chapter 7 GHC has a comprehensive optimiser so when you want to Really Go For It and you ve got time to spare GHC can produce pretty fast code Alternatively the default option is to compile as fast as possible while not making too much effort to optimise the generated code although GHC probably isn t what you d describe as a fast compiler GHC s profiling system supports cost centre stacks a way of seeing the profile of a Haskell program in a call graph like structure See Chapter 5 for more details GHC comes with a number of libraries These are described in separate documentation 1 1 Obtaining GHC Go to the GHC home page and follow the download link to download GHC for your platform Alternatively if you want to build GHC yourself head on over to the GHC Building Guide to find out how to get the sources and build it on your system Note that GHC itself is written in Haskell so you will still need to install GHC in order to build it 1 2 Meta information We
351. et and where bindings name shadowing is not allowed within an mdo expression or a rec block that is all the names bound in a single rec must be distinct GHC will complain if this is not the case 7 3 13 Parallel List Comprehensions Parallel list comprehensions are a natural extension to list comprehensions List comprehensions can be thought of as a nice syntax for writing maps and filters Parallel comprehensions extend this to include the zipWith family A parallel list comprehension has multiple independent branches of qualifier lists each separated by a l symbol For example the following zips together two lists ETS amp lt 3s vy lt ws The behaviour of parallel list comprehensions follows that of zip in that the resulting list will have the same length as the shortest branch We can define parallel list comprehensions by translation to regular comprehensions Here s the basic idea Given a parallel comprehension of the form Ce wil lt ell 2 lt elz sil lt G2 Ce lt G22 This will be translated to Se i p2 a acc lt Zao O pi lt Gill WA lt GZ sool CUATE oil lt zi 2 lt 622 sool where zipN is the appropriate zip for the given number of branches 7 3 14 Generalised SQL Like List Comprehensions Generalised list comprehensions are a further enhancement to the list comprehension syntactic sugar to allow operations such as sorting and grouping which are f
352. everal sub commands The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 145 327 hpe Usage hpc COMMAND Commands help Display help for hpc or a single command Reporting Coverage ESPOUE Output textual report about program coverage markup Markup Haskell source with program coverage Processing Coverage files sum Sum multiple tix files in a single tix file combine Combine two tix files in a single tix file map Map a function over a single tix file Coverage Overlays overlay Generate a tix file from an overlay file draft Generate draft overlay that provides 100 coverage Others show Show tix file in readable verbose format version Display version for hpc In general these options act on a t ix file after an instrumented binary has generated it The hpc tool assumes you are in the top level directory of the location where you built your application and the tix file is in the same top level directory You can use the flag srcdir to use hpc for any other directory and use srcdir multiple times to analyse programs compiled from difference locations as is typical for packages We now explain in more details the major modes of hpc 5 7 3 1 hpc report hpc report gives a textual report of coverage By default all modules and packages are considered in generating report unless include or exclude are used The report is a summary unless the per module flag is used The xml o
353. exed vectors data Ze data Sun The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 220 327 data Vec x gt x gt x wher Nil Vec a Ze Cons se a Vec a n gt Wee a O m The kind of Vec is x gt gt x This means that eg Vec Int Char is a well kinded type even though this is not what we intend when defining length indexed vectors With XDataKinds the example above can then be rewritten to data Nat Ze Su Nat cete vac 28 gt Nart gt lt wier Nil Vec a Ze Cons 88 a gt Wee a in gt Wee a Su im With the improved kind of Vec things like Vec Int Char are now ill kinded and GHC will report an error 7 9 2 Overview With XDataKinds GHC automatically promotes every suitable datatype to be a kind and its value constructors to be type constructors The following types data Nat Ze Su Nat data List a Nil Cons a List a data Pair a b Pairab data Sum ab La l Rb give rise to the following kinds and type constructors Nene 8 8 BO ae 11 Nat SUN NS ES E O WAL 28 base ls AOS AS S ik Par r Il 122 BOX Pair Er kl gt Ka gt Pale EL R2 SUIS O i 38 kil gt Sui kil RZ IR ge k2 gt Sum kil KZ where BOX is the unique sort that classifies kinds Note that List for instance does not get sort BOX gt BOX because we do not further classify kinds all kinds have sort BOX The following restrictions apply
354. f Definition 5 Relaxed Conditions of Type Checking with Open Type Functions Instance declarations have the general form type instance Prik iil ic where we require that for every type family application G s1 sm int 1 s1 smdo not contain any type family constructors 2 the total number of symbols data type constructors and type variables ins1 smis strictly smaller thanint1 tn and 3 for every type variable a a occurs in s1 sm at most as often asint1l tn These restrictions are easily verified and ensure termination of type inference However they are not sufficient to guarantee com pleteness of type inference in the presence of so called loopy equalities such as a F a where a recursive occurrence of a type variable is underneath a family application and data constructor application see the above mentioned paper for details If the option XUndecidablelnstances is passed to the compiler the above restrictions are not enforced and it is on the programmer to ensure termination of the normalisation of type families during type inference 7 7 3 Associated data and type families A data or type synonym family can be declared as part of a type class thus class GMapKey k where data GMap k gt x class Collects ce where type Elem ce x When doing so we optionally may drop the family keyword The type parameters must all be type variables of course and some but not necessarily
355. f the form x t gt t which says this function uses a dynamically bound variable x of type t For example the following expresses the type of a sort function implicitly parameterized by a comparison function named cmp some se Peis 23 e gt a gt Bool gt lal gt el The dynamic binding constraints are just a new form of predicate in the type class system An implicit parameter occurs in an expression using the special form x where x is any valid identifier e g ord xisa valid expression Use of this construct also introduces a new dynamic binding constraint in the type of the expression For example the following definition shows how we can define an implicitly parameterized sort function in terms of an explicitly parameterized sort By function sorty s a gt gt Bol gt lal gt led sort 38 Pens 24 gt a gt Bool gt lel gt al sort SORBAS Cno 7 13 4 1 Implicit parameter type constraints Dynamic binding constraints behave just like other type class constraints in that they are automatically propagated Thus when a function is used its implicit parameters are inherited by the function that called it For example our sort function might be used to pick out the least value in a list least oR Hemos 82 2 gt a gt Bol gt lal gt e least xs head sort xs Without lifting a finger the cmp parameter is propagated to become a parameter of least as well With explicit para
356. fenable rewrite rules is an optimisation flag and has no effect on parsing or typechecking Rules are regarded as left to right rewrite rules When GHC finds an expression that is a substitution instance of the LHS of a tule it replaces the expression by the appropriately substituted RHS By a substitution instance we mean that the LHS can be made equal to the expression by substituting for the pattern variables GHC makes absolutely no attempt to verify that the LHS and RHS of a rule have the same meaning That is undecidable in general and infeasible in most interesting cases The responsibility is entirely the programmer s GHC makes no attempt to make sure that the rules are confluent or terminating For example oops OLE E Yo fF MR WS 1 Wy Se This rule will cause the compiler to go into an infinite loop If more than one rule matches a call GHC will choose one arbitrarily to apply GHC currently uses a very simple syntactic matching algorithm for matching a rule LHS with an expression It seeks a substitution which makes the LHS and expression syntactically equal modulo alpha conversion The pattern rule but not the expression is eta expanded if necessary Eta expanding the expression can lead to laziness bugs But not beta conversion that s called higher order matching Matching is carried out on GHC s intermediate language which includes type abstractions and applications So a rule only matches if the typ
357. flag is also used to lift some of the restricitions imposed on type family instances See Section 7 7 2 6 7 6 3 5 Overlapping instances In general as discussed in Section 7 6 3 1 GHC requires that it be unambiguous which instance declaration should be used to resolve a type class constraint GHC also provides a way to to loosen the instance resolution by allowing more than one instance to match provided there is a most specific one Moreover it can be loosened further by allowing more than one instance to match irespective of whether there is a most specific one This section gives the details To control the choice of instance it is possible to specify the overlap behavior for individual instances with a pragma written immediately after the instance keyword The pragma may be one of fOVERLAPPING OVERLAPPABLE OVERLAPS or INCOHERENT The matching behaviour is also influenced by two module level language extension flags KOverlappingInstances and XIncoherentInstances These flags are now deprecated since GHC 7 10 in favour of the fine grained per instance pragmas A more precise specification is as follows The willingness to be overlapped or incoherent is a property of the instance declaration itself controlled as follows e An instance is incoherent if it has an INCOHERENT pragma or if the instance has no pragma and it appears in a module compiled w
358. foo x x Iiquceucmeycls O Wi Wo wih filter Ea filter filter Els ENS Eorall ay a gt Boo gt all a americas E gt Ieu gt led gt led The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 241 327 7 15 1 2 Named Wildcards Type wildcards can also be named by giving the underscore an identifier as suffix i e _a These are called named wildcards All occurrences of the same named wildcard within one type signature will unify to the same type For example if 88 3S ES E Cer Ww a error vurk Inferred forall w Char gt Char El The named wildcard forces the argument and result types to be the same Lacking a signature GHC would have inferred forall a b Char a gt Char b A named wildcard can be mentioned in constraints provided it also occurs in the monotype part of the type signature to make sure that it unifies with something somethingShowable Show _x gt _x gt somethingShowable x show x Inferred type Show w_x gt w_x gt String somethingShowable Show _x gt _x gt _ somethingShowable x show not x Inferred type Bool gt String Besides an extra constraints wildcard see Section 7 15 1 3 only named wildcards can occur in the constraints e g the _x in Show _x Named wildcards should not be confused with type variables Even though syntactically similar named wildcards can unify with monoty
359. for allowing lone wild card patterns is they are not very different from _v rhs3 which elicits no warning and they can be useful to add a type constraint e g _ x Int A lone banged wild card pattern is is useful as an alternative to seq way to force evaluation fwarn unused imports Report any modules that are explicitly imported but never used However the form import M is never reported as an unused import because it is a useful idiom for importing instance declarations which are anonymous in Haskell fwarn unused matches Report all unused variables which arise from pattern matches including patterns consisting of a single variable For instance f x y would report x and y as unused The warning is suppressed if the variable name begins with an underscore thus f _x True fwarn unused do bind Report expressions occurring in do and mdo blocks that appear to silently throw information away For instance do mapM popInt xs return 10 would report the first statement in the do block as suspicious as it has the type StackM Int andnot StackM but that Int value is not bound to anything The warning is suppressed by explicitly mentioning in the source code that your program is throwing something away Ce lt mej Colic ks worm 10 Of course in this particular situation you can do even better do mapM_ popInt xs return 10 fwarn context quantification Report if a variable is quantified only d
360. for information on how to report it 1 4 GHC version numbering policy As of GHC version 6 8 we have adopted the following policy for numbering GHC versions Stable Releases Stable branches are numbered x y where y is even Releases on the stable branch x y are numbered x y z where z gt 1 is the patchlevel number Patchlevels are bug fix releases only and never change the programmer interface to any system supplied code However if you install a new patchlevel over an old one you will need to recompile any code that was compiled against the old libraries The value of __GLASGOW_HASKELL___ see Section 4 12 3 for a major release x y z is the integer xyy if y is a single digit then a leading zero is added so for example in version 6 8 2 of GHC we would have _ GLASGOW_HASKELL__ 608 Stable snapshots We may make snapshot releases of the current stable branch available for download and the latest sources are available from the git repositories Stable snapshot releases are named x y z YYYYMMDD where YYYYMMDD is the date of the sources from which the snap shot was built and x y z 1 is the next release to be made on that branch For example 6 8 1 20040225 would be a snapshot of the 6 8 branch during the development of 6 8 2 The value of _ GLASGOW_HASKELL_ fora snapshot release is the integer xyy You should never write any conditional code which tests for this value however since interfaces change on
361. form word where word indicates the type of pragma and is followed optionally by informa tion specific to that type of pragma Case is ignored in word The various values for word that GHC understands are described in the following sections any pragma encountered with an unrecognised word is ignored The layout rule applies in pragmas so the closing should start in a column to the right of the opening Certain pragmas are file header pragmas The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 260 327 e A file header pragma must precede the module keyword in the file e There can be as many file header pragmas as you please and they can be preceded or followed by comments e File header pragmas are read once only before pre processing the file e g with cpp e The file header pragmas are fLANGUAGE OPTIONS_GHC and INCLUDE 7 22 1 LANGUAGE pragma The LANGUAGE pragma allows language extensions to be enabled in a portable way It is the intention that all Haskell compilers support the LANGUAGE pragma with the same syntax although not all extensions are supported by all compilers of course The LANGUAGE pragma should be used instead of OPTIONS_GHC if possible For example to enable the FFI and preprocessing with CPP LANGUAGE ForeignFunctionInterface CPP LANGUAGE is a file header pragma see Sec
362. form specific optimisations compiled in usually because this is a currently unsupported platform This value will usually be no unless you re using an experimental build of GHC Tables next to code Putting info tables directly next to entry code is a useful performance optimisation that is not available on all platforms This field tells you whether the program has been compiled with this optimisation Usually yes except on unusual platforms 4 18 Debugging the compiler HACKER TERRITORY HACKER TERRITORY You were warned 4 18 1 Dumping out compiler intermediate structures ddump pass Make a debugging dump after pass lt pass gt may be common enough to need a short form You can get all of these at once lots of output by using v5 or most of them with v4 You can prevent them from clogging up your standard output by passing ddump to file Some of the most useful ones are ddump parsed parser output ddump rn renamer output ddump te typechecker output ddump splices Dump Template Haskell expressions that we splice in and what Haskell code the expression evaluates to ddump types Dump a type signature for each value defined at the top level of the module The list is sorted alphabetically Using dppr debug dumps a type signature for all the imported and system defined things as well useful for debugging the compiler ddump deriv derived instances ddump ds desugarer output ddump spec
363. ful when compiling with ffull laziness as is default with O and higher as constants in function bodies will be lifted to the top level and become CAFs You will probably need to consult the Core ddump simp1 in order to determine what these CAFs correspond to 5 2 Compiler options for profiling prof To make use of the profiling system all modules must be compiled and linked with the prof option Any SCC annotations you ve put in your source will spring to life Without a prof option your SCCs are ignored so you can compile SCC laden code without changing it There are a few other profiling related compilation options Use them in addition to prof These do not have to be used consistently for all modules in a program fprof auto All bindings not marked INLINE whether exported or not top level or nested will be given automatic SCC annotations Functions marked INLINE must be given a cost centre manually fprof auto top GHC will automatically add SCC annotations for all top level bindings not marked INLINE If you want a cost centre on an INLINE function you have to add it manually fprof auto exported GHC will automatically add SCC annotations for all exported functions not marked INLINE If you want a cost centre on an INLINE function you have to add it manually The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 136 327 fprof auto calls Adds an automatic SCC annotation to
364. g module are used with rebindable syntax the operators are looked up in the current lexical scope For example parallel comprehensions will be typechecked and desugared using whatever mz ip is in scope The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 169 327 The rebindable operators must have the Expected type given in the table above These types are surprisingly general For example you can use a bind operator with the type 5 32 Tos y a gt a gt Ty 2 lo gt Wx 2 lo In the case of transform comprehensions notice that the groups are parameterised over some arbitrary type n provided it has an fmap as well as the comprehension being over an arbitrary monad 7 3 16 Rebindable syntax and the implicit Prelude import GHC normally imports Prelude hi files for you If you d rather it didn t then give it a XNoImplicitPrelude 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 Suppose you are importing a Prelude of your own in order 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 XRebindableSyntax flag causes the following pieces of built in syntax to refer to whatever is in scope not the Prelude versions e An integer
365. g A does not export g q i The import A hiding g in module B is technically an error Haskell Report 5 3 1 because A does not export g However GHC allows it in the interests of supporting backward compatibility for example a newer version of A might export g and you want B to work in either case The warning fwarn dodgy imports which is off by default but included with W warns if you hide something that the imported module does not export 7 3 26 2 Package qualified imports With the XPackageImport s flag GHC allows import declarations to be qualified by the package name that the module is intended to be imported from For example import network Network Socket would import the module Network Socket from the package net work any version This may be used to disambiguate an import when the same module is available from multiple packages or is present in both the current package being built and an external package The special package name this can be used to refer to the current package being built Note you probably don t need to use this feature it was added mainly so that we can build backwards compatible versions of packages when APIs change It can lead to fragile dependencies in the common case modules occasionally move from one pack age to another rendering any package qualified imports broken See also Section 4 9 4 for an alternative way of disambiguating between module names The Glorious
366. g out compiler intermediate structures 2 0 a 105 4 18 2 Formmatuine dumps iai ea 084 A AA eee wars ox 106 4 18 3 Suppressing unwanted information 2 2 a 106 4 18 4 Checking for consistency 2 ee 107 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 viii 4 18 5 How to read Core syntax from some ddump flags 2 2 2 2 0 0 000 002 0000 107 4 19 Flag reference osos 220 e a a e Re la ea e a a 108 4 19 1 Verbosity Options s s s woe s ss Tataee E e e E i e a 108 4 19 2 Alternative modes of operation 2 e a 109 4 19 3 Which phases tO TUN 2 ge e E e e e E E a E a T EE a E E a E ER a a 109 4 19 4 Redirecting Output s seces 644 Bee eee e E a e a Be RR SE EE A Se E e e Y 110 4 19 5 Keeping intermediate files s p srs me aii dea koe 02 000 a 0000000000000 0 00000 110 4 19 6 Temporary files oa me eogi cross A e eee ewe E 110 4 19 7 Finding imports s eara RR eE A a a 111 419 8 Interface Hle 0pliODS 25 200 bots we ed Shes AAA yank A Sede Ee 119 4 19 9 Recompilation checking 20 0 000000 0000002 2 eee 111 4 19 10 Interactive mode options 2 a 111 4 19 11 Packages 2 aces ee a ae a o de o ee 112 4 19 12 Language Opuons vom a a SE RAR HE a eR eae a E 112 4 19 13 Warnes cesce ganea ee ra a Pewee bee dd e E E E wd 117 4 19 14 Optimisation levels secese 5 ar a Be Se ARO RAE e oe 120 4 19 15 Individual optimisations a e a e e a a e E a E a a
367. g the program A lexically scoped type variable can be bound by e A declaration type signature Section 7 13 8 2 e An expression type signature Section 7 13 8 3 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 235 327 e A pattern type signature Section 7 13 8 4 e Class and instance declarations Section 7 13 8 5 In Haskell a programmer written type signature is implicitly quantified over its free type variables Section 4 1 2 of the Haskell Report Lexically scoped type variables affect this implicit quantification rules as follows any type variable that is in scope is not universally quantified For example if type variable a is in scope then le 288 gt E means le a gt a te g8 l gt 10 means e ss forall b b gt b less 2 gt lg means le 3 forall b a gt b 7 13 8 2 Declaration type signatures A declaration type signature that has explicit quantification using foral1 brings into scope the explicitly quantified type variables in the definition of the named function For example E 8 forall as lal gt al IIS ses deb fox Se a wow The forall a brings a into scope in the definition of f This only happens if e The quantification in s type signature is explicit For example g ss lal gt fal of iza ss ase ess al n_n 1 This program will be rejected because a does not scope over the definition of g so x a means x f
368. ge is when the package does not contain any Haskell modules it might contain a C library only for example In that case GHC will never discover a dependency on it so it has to be mentioned explicitly For example to link a program consisting of objects Foo o and Main o where we made use of the net work package we need to give GHC the package flag thus The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 68 327 ghc o myprog Foo o Main o package network The same flag is necessary even if we compiled the modules from source because GHC still reckons it s in batch mode ghc o myprog Foo hs Main hs package network package id P Exposes a package like package but the package is named by its installed package ID rather than by name This is a more robust way to name packages and can be used to select packages that would otherwise be shadowed Cabal passes package id flags to GHC package id supports thinning and renaming described in Section 4 9 4 hide all packages Ignore the exposed flag on installed packages and hide them all by default If you use this flag then any packages you require including base need to be explicitly exposed using package options This is a good way to insulate your program from differences in the globally exposed packages and being explicit about package dependencies is a Good Thing Cabal always passes the hide all packages flag to GHC for exactly this re
369. gen and higher Omitting gen disables load balancing entirely Load balancing shares out the work of GC between the available cores This is a good idea when the heap is large and we need to parallelise the GC work however it is also pessimal for the short young generation collections in a parallel program because it can harm locality by moving data from the cache of the CPU where is it being used to the cache of another CPU Hence the default is to do load balancing only in the old generation In fact for a parallel program it is sometimes beneficial to disable load balancing entirely with qb H size Default 0 This option provides a suggested heap size for the garbage collector Think of Hsize as a variable A option It says I want to use at least size bytes so use whatever is left over to increase the A value This option does not put a limit on the heap size the heap may grow beyond the given size as usual If size is omitted then the garbage collector will take the size of the heap at the previous GC as the size This has the effect of allowing for a larger A value but without increasing the overall memory requirements of the program It can be useful when the default small A value is suboptimal as it can be in programs that create large amounts of long lived data Iseconds default 0 3 In the threaded and SMP versions of the RTS see threaded Section 4 12 6 a major GC is automatically performed if the runtime ha
370. ght as possible when parsing SCC stands for Set Cost Centre The double quotes can be omitted if name is a Haskell identifier for example SCC my_function lt expression gt Here is an example of a program with a couple of SCCs MALO main do let xs 1 1000000 let ys 1 2000000 prine A SUS lease ze 5 last zs peinte oe SOC last maite seg Fj lease mie ss PROS CCAA S ES last ys print SCC last_init_ys last init ys which gives this profile when run 2 Note that this policy has changed slightly in GHC 7 4 1 relative to earlier versions and may yet change further feedback is welcome The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 135 327 COST CENTRE MODULE no entries time alloc Stime Salloc MAIN MAIN 102 0 ORO ORO 100 0 100 0 CAF GHC IO Handle FD 130 0 0 0 0 0 0 0 ORO CAF GHC IO Encoding Iconv LBZ 0 0 0 0 0 0 0 0 0 CAF GHC Conc Signal LLI 0 0 0 0 0 ORO 050 CAF ain 108 0 omo 00 100 0 100 0 main ain 204 al 00 00 IOC 0 1O00 Last a oiie 3 8 Meun 210 il B33 0 27 4 ZO 27 4 main ys ain 209 AL 25 50 D5 2 ZO S252 last_ys ain 208 il 2785 0 0 12 3 0 0 last_init_xs Main 207 il 55 LS 7 J25 TOTE main xs ain 206 T SES 1 0 ESTAS US last xs ain A05 T 6 2 0 0 OREZ 010 5 1 2 Rules for attributing costs While running a program with profiling turned on GHC maintains a cost centre stack behind the scenes and attribut
371. ght the active subexpression in bold load module Recursively loads the specified modules and all the modules they depend on Here each module must be a module name or filename but may not be the name of a module in a package All previously loaded modules except package modules are forgotten The new set of modules is known as the target set Note that load can be used without any arguments to unload all the currently loaded modules and bindings Normally pre compiled code for a module will be loaded if available or otherwise the module will be compiled to byte code Using the x prefix forces a module to be loaded as byte code After a load command the current context is set to module if it was loaded successfully or e the most recently successfully loaded module if any other modules were loaded as a result of the current load or e Prelude otherwise main arg arg When a program is compiled and executed it can use the getArgs function to access the command line arguments However we cannot simply pass the arguments to the main function while we are testing in ghci as the main function doesn t take its arguments directly Instead we can use the main command This runs whatever main is in scope with any arguments being treated the same as command line arguments e g Prelude gt let main System Environment getArgs gt gt print Prelude gt main foo bar toa sal We can also quote arguments w
372. gister allocation fsimplifier phases n Set the number of phases for the simplifier default 2 Ignored with O0 fsimpl tick factor n GHC s optimiser can diverge if you write rewrite rules Section 7 23 that don t terminate or less satisfactorily if you code up recursion through data types Section 13 2 1 To avoid making the compiler fall into an infinite loop the optimiser carries a tick count and stops inlining and applying rewrite rules when this count is exceeded The limit is set as a multiple of the program size so bigger programs get more ticks The fsimpl tick factor flag lets you change the multiplier The default is 100 numbers larger than 100 give more ticks and numbers smaller than 100 give fewer If the tick count expires GHC summarises what simplifier steps it has done you can use fddump simpl stats to generate a much more detailed list Usually that identifies the loop quite accurately because some numbers are very large fspec constr Off by default but enabled by O2 Turn on call pattern specialisation see Call pattern specialisation for Haskell programs This optimisation specializes recursive functions according to their argument shapes This is best explained by example so consider The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 82 327 last ss a gt a last error last lest 8 MM z Last x xs last xs In this code once we pass the ini
373. gow Haskell Compilation System User s Guide Version 7 10 2 116 327 Flag Description Static Dynamic Reverse Enable parallel list ea es A XNoParallelListcC XParallelListComp comprehensions Implied dynamic ae by XParallelArrays XPartialTypeSigna Enable partial type dviamie XNoPartialTypeSig tures signatures y natures XPatternGuards Enable pattern guards dynamic XNoPatternGuards XPatt S Enable pattern synonyms dynamic e nr RATA p Pag y XNoPatternSynonyms Enable kind polymorphism XPolyKinds Implies dynamic XNoPolyKinds XKindSignatures Enable polymorphic l XPolymorphicCompo dynamic synonym for XNoPolymorphicCom components for data nents XRankNTypes ponents constructors XNoPostfixO t XPostfixOperators Enable postfix operators dynamic Dir AO XQuasiQuotes Enable quasiquotation dynamic XNoQuasiQuotes dynamic synonym for XRank2Types Enable rank 2 types y n SITOR XNoRank2Types XRankNTypes Enable rank N types XRankNTypes Implied by XImpredica dynamic XNoRankNTypes tiveTypes Employ rebindable syntax E P y y XNoRebindableSyn XRebindableSyntax Implies dynamic ES x XNoImplicitPrelude Enable record wildcards B XR Wil Implies XDi d i i ecordWildCards mplies Teambiguat ynamic XNoRecordWildCards eRecordFields Enable recursive do mdo XRecurs
374. gration only applies to threads sparks created by par are load balanced separately by work stealing This option is probably only of use for concurrent programs that explicitly schedule threads onto CPUs with Control Concurrent forkOn 4 15 3 Hints for using SMP parallelism Add the s RTS option when running the program to see timing stats which will help to tell you whether your program got faster by using more CPUs or not If the user time is greater than the elapsed time then the program used more than one CPU You should also run the program without N for comparison The output of RTS s tells you how many sparks were created and executed during the run of the program see Sec tion 4 17 3 which will give you an idea how well your par annotations are working GHC s parallelism support has improved in 6 12 1 as a result of much experimentation and tuning in the runtime system We d still be interested to hear how well it works for you and we re also interested in collecting parallel programs to add to our benchmarking suite 4 16 Platform specific Flags Some flags only make sense for particular target platforms msse2 x86 only added in GHC 7 0 1 Use the SSE2 registers and instruction set to implement floating point operations when using the native code generator This gives a substantial performance improvement for floating point but the resulting compiled code will only run on processors that support SSE2 I
375. guments can also be given explicit kind signatures if needed Just as with http www haskell org ghc docs latest html users_ gu GADT declarations named arguments are entirely optional so that we can declare Array alternatively with Gaita ranita O g3 n SS 7 7 1 2 Data instance declarations Instance declarations of data and newtype families are very similar to standard data and newtype declarations The only two differences are that the keyword data or newt ype is followed by instance and that some or all of the type arguments can be non variable types but may not contain forall types or type synonym families However data families are generally allowed in type parameters and type synonyms are allowed as long as they are fully applied and expand to a type that is itself admissible exactly as this is required for occurrences of type synonyms in class instance parameters For example the Either instance for GMap is data instance GMap Either a b v GMapEither GMap av GMap b v In this example the declaration has only one variant In general it can be any number Data and newtype instance declarations are only permitted when an appropriate family declaration is in scope just as a class instance declaration requires the class declaration to be visible Moreover each instance declaration has to conform to the kind determined by its family declaration This implies that the number of parameters of an instance declaration matches
376. h as Ghostview or print it out on a Postscript capable printer The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 137 327 q RTS h bytes 5M 45M 40M_ 35M 3M 25M 20M 15M_ OM 5M OM For example here is a heap profile produced for the program given above in Section 5 1 1 00 0 2 You might also want to take a look at hp2any a more advanced suite of tools not distributed with GHC for displaying heap profiles 5 4 1 RTS options for heap profiling There are several different kinds of heap profile that can be generated All the different profile types yield a graph of live heap against time but they differ in how the live heap is broken down into bands The following RTS options select which break down to use hc can be shortened to h Breaks down the graph by the cost centre stack which produced the data hm Break down the live heap by the module containing the code which produced the data hd Breaks down the graph by closure description For actual data the description is just the constructor name for other closures it is a compiler generated string identifying the closure hy Breaks down the graph by type For closures which have function type or unknown polymorphic type the string will represent an approximation to the actual type hr Break down the graph by retainer set Retainer profiling is described in more detail below Section 5 4 2 hb Bre
377. he MINIMAL pragma is used to specify the minimal complete definition of a class I e specify which methods must be implemented by all instances If an instance does not satisfy the minimal complete definition then a warning is generated This can be useful when a class has methods with circular defaults For example class Eq a where 86 al gt a gt kool US 8 a gt a gt Bool x y not x y x y not x y oi Mia 1 2 4 Without the MINIMAL pragma no warning would be generated for an instance that implements neither method The syntax for minimal complete definition is minderi E mens CU mainder y mindef mindef mindef mindef A vertical bar denotes disjunction i e one of the two sides is required A comma denotes conjunction i e both sides are required Conjunction binds stronger than disjunction If no MINIMAL pragma is given in the class declaration it is just as if a pragma MINIMAL opl op2 Opn was given where the opi are the methods a that lack a default method in the class declaration and b whose name that does not start with an underscore c f fwarn missing methods Section 4 8 This warning can be turned off with the flag fno warn missing methods 7 22 6 INLINE and NOINLINE pragmas These pragmas control the inlining of function definitions 7 22 6 1 INLINE pragma GHC with O as always tries to inline or unfold
378. he exact precision range of Float Double values and should not use this option for their compilation Note that the 32 bit x86 native code generator only supports excess precision mode so neither fexcess precision nor fno excess precision has any effect This is a known bug see Section 13 2 1 fexpose all unfoldings An experimental flag to expose all unfoldings even for very large or recursive functions This allows for all functions to be inlined while usually GHC would avoid inlining larger functions ffloat in On by default Float let bindings inwards nearer their binding site See Let floating moving bindings to give faster programs ICFP 96 This optimisation moves let bindings closer to their use site The benefit here is that this may avoid unnecessary allocation 1f the branch the let is now on is never executed It also enables other optimisation passes to work more effectively as they have more information locally This optimisation isn t always beneficial though so GHC applies some heuristics to decide when to apply it The details get complicated but a simple example is that it is often beneficial to move let bindings outwards so that multiple let bindings can be grouped into a larger single let binding effectively batching their allocation and helping the garbage collector and allocator ffull laziness On by default Run the full laziness optimisation also known as let floating which floats let bindings outside enc
379. he linker to use default gcc C FLAG or cflag FLAG An extra flag to pass to the C compiler The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 306 327 I DIR Passed to the C compiler L FLAG or 1flag FLAG An extra flag to pass to the linker i FILE or include FILE As if the appropriate tinclude directive was placed in the source D NAME VALUE or define NAME VALUE As if the appropriate define directive was placed in the source no compile Stop after writing out the intermediate C program to disk The file name for the intermediate C program is the input file name with hsc replaced with _hsc_make c k or keep files Proceed as normal but do not delete any intermediate files x or cross compile Activate cross compilation mode see Section 11 2 4 cross safe Restrict the hsc directives to those supported by the cross compile mode see Section 11 2 4 This should be useful if your hsc files must be safely cross compiled and you wish to keep non cross compilable constructs from creeping into them or help Display a summary of the available flags and exit successfully V or version Output version information and exit successfully The input file should end with hsc 1t should be plain Haskell source only literate Haskell is not supported at the moment Output files by default get names with the hsc suffix replaced hs Haskell file
380. he unifier to be infinite disallows the following pair of instances type instance H x ae type instance H x x Bool The type patterns in this pair equal if x is replaced by an infinite nesting of lists Rejecting instances such as these is necessary for type soundness Compatibility also affects closed type families When simplifying an application of a closed type family GHC will select an equation only when it is sure that no incompatible previous equation will ever apply Here are some examples type family F a where Hine BOO Fa Char type family G a where oye INE Ga Sal In the definition for F the two equations are incompatible their patterns are not apart and yet their right hand sides do not coincide Thus before GHC selects the second equation it must be sure that the first can never apply So the type F a does not simplify only a type such as F Double will simplify to Char In G on the other hand the two equations are compatible Thus GHC can ignore the first equation when looking at the second So G a will simplify to a However see Section 2 4 4 for the overlap rules in GHCi The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 212 327 7 7 2 6 Decidability of type synonym instances In order to guarantee that type inference in the presence of type families decidable we need to place a number of additional restrictions on the formation of type instance declarations c
381. he warning is suppressed if the method name begins with an underscore Here s an example where this is useful class C a where SMC 88 El gt Sicilia Comole aa 98 gt E gt Sieieiing complexFn x y _SimpleFn The idea is that a users of the class will only call complexFn never _simpleFn and b instance declarations can define either complexFn or _simpleFn The MINIMAL pragma can be used to change which combination of methods will be required for instances of a particular class See Section 7 22 5 fwarn missing signatures If you would like GHC to check that every top level function value has a type signature use the fwarn missing signatures option As part of the warning GHC also reports the inferred type The option is off by default The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 64 327 fwarn missing exported sigs If you would like GHC to check that every exported top level function value has a type signature but not check unexported values use the fwarn missing exported sigs option This option takes precedence over fwarn missing signatures As part of the warning GHC also reports the inferred type The option is off by default fwarn missing local sigs If you use the fwarn missing local sigs flag GHC will warn you about any polymorphic local bindings As part of the warning GHC also reports the inferred type The option is off by default fwarn name shadow
382. hen the positive and negative range of a numeric data type don t match up For example in 8 bit arithmetic 128 is representable but 128 is not So negate fromInteger 128 will elicit an unexpected integer literal overflow message 7 3 4 Fractional looking integer literals Haskell 2010 and Haskell 98 define floating literals with the syntax 1 2e6 These literals have the type Fractional a gt a The language extension XNumDecimals allows you to also use the floating literal syntax for instances of Integral and have values like 1 2e6 Num a gt a 7 3 5 Binary integer literals Haskell 2010 and Haskell 98 allows for integer literals to be given in decimal octal prefixed by 0o or 00 or hexadecimal notation prefixed by 0x or 0X The language extension XBinaryLiterals adds support for expressing integer literals in binary notation with the prefix Ob or OB For instance the binary integer literal 0011001001 will be desugared into fromInteger 201 when XBinaryLi terals is enabled The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 156 327 7 3 6 Hierarchical Modules GHC supports a small extension to the syntax of module names a module name is allowed to contain a dot This is also known as the hierarchical module namespace extension because it extends the normally flat Haskell module namespace into a more flexible hierarchy of modules This extension has very little impact on the
383. here for some particular types t and s the only variables that can appear in s are the ones that appear in t and hence if the type t is known then s will be uniquely determined The benefit of including dependency information is that it allows us to define more general multiple parameter classes without ambiguity problems and with the benefit of more accurate types To illustrate this we return to the collection class example and annotate the original definition of Collects with a simple dependency class Collects ce c gt wher CMA CE alms erti n gt poe member gt 0 BOO The dependency ce gt e here specifies that the type e of elements is uniquely determined by the type of the collection ce Note that both parameters of Collects are of kind there are no constructor classes here Note too that all of the instances of Collects that we gave earlier can be used together with this new definition What about the ambiguity problems that we encountered with the original definition The empty function still has type Collects e ce gt ce but itis no longer necessary to regard that as an ambiguous type Although the variable e does not appear on the right of the gt symbol the dependency for class Collects tells us that it is uniquely determined by ce which does appear on the right of the gt symbol Hence the context in which empty is used can still give enough information to determine types for both ce and e Withou
384. hich contains characters like spaces and they are treated like Haskell strings or we can just use Haskell list syntax Prelude gt main foo bar baz tonta Daz Prelude gt main foo bar baz PARO al Finally other functions can be called either with the main is flag or the run command Prelude gt let foo putStrLn foo gt gt System Environment getArgs gt gt print Prelude gt let bar putStrLn bar gt gt System Environment getArgs gt gt print Prelude gt set main is foo Prelude gt main foo bar baz foo foo bar baz The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 37 327 Prelude seur ber too ber baz bar ECON AMO Ia module x mod mod import mod Sets or modifies the current context for statements typed at the prompt The form import mod is equivalent to module mod See Section 2 4 5 for more details print names Prints a value without forcing its evaluation print may be used on values whose types are unknown or partially known which might be the case for local variables with polymorphic types at a breakpoint While inspecting the runtime value print attempts to reconstruct the type of the value and will elaborate the type in GHCi s environment if possible If any unevaluated components thunks are encountered then print binds a fresh variable with a name beginning with _t to each thunk See Section
385. hink of the object file and the interface file as a pair since the interface file is in a sense a compiler readable description of the contents of the object file If the interface file and object file get out of sync for any reason then the compiler may end up making assumptions about the object file that aren t true trouble will almost certainly follow For this reason we recommend keeping object files and interface files in the same place GHC does this by default but it is possible to override the defaults as we ll explain shortly Every module has a module name defined in its source code nodule A B C where The name of the object file generated by GHC is derived according to the following rules where osuf is the object file suffix this can be changed with the osuf option e If there is no odir option the default then the object filename is derived from the source filename ignoring the module name by replacing the suffix with osuf e If odir dir has been specified then the object filename is dir mod osuf where mod is the module name with dots replaced by slashes GHC will silently create the necessary directory structure underneath di r if it does not already exist The name of the interface file is derived using the same rules except that the suffix is hisuf hi by default instead of osuf and the relevant options are hidir and hisuf instead of odir and osuf respectively For example if GHC compiles the mo
386. i interactive print SpecPrinter sprinter SpecPrinter will start an interactive session where values with be printed using sprint SpecPrinter gt 1 2 3 CASA SpecPrinter gt 42 42 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 24 327 A custom pretty printing function can be used for example to format tree like and nested structures in a more readable way The interactive print flag can also be used when running GHC in e mode a ghc e 1 2 3 interactive print SpecPrinter sprint SpecPrinter 2 5 The GHCi Debugger GHCi contains a simple imperative style debugger in which you can stop a running computation in order to examine the values of variables The debugger is integrated into GHCi and is turned on by default no flags are required to enable the debugging facilities There is one major restriction breakpoints and single stepping are only available in interpreted modules compiled code is invisible to the debugger The debugger provides the following e The ability to set a breakpoint on a function definition or expression in the program When the function is called or the expression evaluated GHCi suspends execution and returns to the prompt where you can inspect the values of local variables before continuing with the execution e Execution can be single stepped the evaluator will suspend execution approximately after every reduction allowing local variables to be
387. ic Tell the linker to avoid shared Haskell libraries if possible This is the default dynamic This flag tells GHC to link against shared Haskell libraries This flag only affects the selection of dependent libraries not the form of the current target see shared See Section 4 13 on how to create them Note that this option also has an effect on code generation see above shared Instead of creating an executable GHC produces a shared object with this linker flag Depending on the operating system target this might be an ELF DSO a Windows DLL or a Mac OS dylib GHC hides the operating system details beneath this uniform flag The flags dynamic static control whether the resulting shared object links statically or dynamically to Haskell package libraries given as package option Non Haskell libraries are linked as gcc would regularly link it on your system e g on most ELF system the linker uses the dynamic libraries when found Object files linked into shared objects must be compiled with fP IC see Section 4 12 5 When creating shared objects for Haskell packages the shared object must be named properly so that GHC recognizes the shared object when linked against this package See shared object name mangling dynload This flag selects one of a number of modes for finding shared libraries at runtime See Section 4 13 4 for a description of each mode main is thing The normal rule in Haskell is that your program must supply
388. ication of given constraints and after unflattening of wanted constraints The two phases can be distinguished because the deriveds and wanteds will be empty in the first case In each case the plugin should either The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 302 327 e return TcPluginContradiction with a list of impossible constraints which must be a subset of those passed in so they can be turned into errors or e return TcPluginOk with lists of solved and new constraints the former must be a subset of those passed in and must be supplied with corresponding evidence terms If the plugin cannot make any progress it should return TcPluginOk Otherwise if there were any new constraints the main constraint solver will be re invoked to simplify them then the plugin will be invoked again The plugin is responsible for making sure that this process eventually terminates Plugins are provided with all available constraints including equalities and typeclass constraints but it is easy for them to discard those that are not relevant to their domain because they need return only those constraints for which they have made progress either by solving or contradicting them Constraints that have been solved by the plugin must be provided with evidence in the form of an EvTerm of the type of the constraint This evidence is ignored for given and derived constraints which GHC solves simply by di
389. ier producing a program that gobbles less heap space I think I have a space leak Re run your program with RTS S and remove all doubt You ll see the heap usage get bigger and bigger Hmmm this might be even easier with the G1 RTS option so a out RTS S G1 Once again the profiling facilities Chapter 5 are the basic tool for demystifying the space behaviour of your program Strict functions are good for space usage as they are for time as discussed in the previous section Strict functions get right down to business rather than filling up the heap with closures the system s notes to itself about how to evaluate something should it eventually be required The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 152 327 Chapter 7 GHC Language Features As with all known Haskell systems GHC implements some extensions to the language They can all be enabled or disabled by command line flags or language pragmas By default GHC understands the most recent Haskell version it supports plus a handful of extensions Some of the Glasgow extensions serve to give you access to the underlying facilities with which we implement Haskell Thus you can get at the Raw Iron if you are willing to write some non portable code at a more primitive level You need not be stuck on performance because of the implementation costs of Haskell s high level features you can always code
390. if a definition such as the above should be feasible However type families are in contrast to GADTs are open i e new instances can always be added possibly in other modules Supporting pattern matching across different data instances would require a form of extensible case construct 7 7 1 3 Overlap of data instances The instance declarations of a data family used in a single program may not overlap at all independent of whether they are associated or not In contrast to type class instances this is not only a matter of consistency but one of type safety 7 7 2 Synonym families Type families appear in three flavours 1 they can be defined as open families on the toplevel 2 they can be defined as closed families on the toplevel or 3 they can appear inside type classes in which case they are known as associated type synonyms Toplevel families are more general as they lack the requirement for the type indexes to coincide with the class parameters However associated type synonyms can lead to more clearly structured code and compiler warnings if some type instances were possibly accidentally omitted In the following we always discuss the general toplevel forms first and then cover the additional constraints placed on associated types Note that closed associated type synonyms do not exist 7 7 2 1 Type family declarations Open indexed type families are introduced by a signature such as type family Elem c x
391. in Compiling to object code takes longer but typically the code will execute 10 20 times faster than byte code Compiling to object code inside GHCi is particularly useful if you are developing a compiled application because the reload command typically runs much faster than restarting GHC with make from the command line because all the interface files are already cached in memory There are disadvantages to compiling to object code you can t set breakpoints in object code modules for example Only the exports of an object code module will be visible in GHCi rather than all top level bindings as in interpreted modules 2 11 FAQ and Things To Watch Out For The interpreter can t load modules with foreign export declarations Unfortunately not We haven t implemented it yet Please compile any offending modules by hand before loading them into GHCi O doesn t work with GHCi For technical reasons the bytecode compiler doesn t interact well with one of the optimisation passes so we have disabled optimisation when using the interpreter This isn t a great loss you ll get a much bigger win by compiling the bits of your code that need to go fast rather than interpreting them with optimisation turned on Unboxed tuples don t work with GHCi That s right You can always compile a module that uses unboxed tuples and load it into GHCi however Incidentally the previous point namely that O is incompatible with GHCi is beca
392. in the program Examples of dependencies like this includea gt a a gt a a a gt etc There can also be some redundancy if multiple dependencies are given as in a gt b b gt c a gt c _ and in which some subset implies the remaining dependencies Examples like this are not treated as errors Note that dependencies appear only in class declarations and not in any other part of the language In particular the syntax for instance declarations class constraints and types is completely unchanged By including dependencies in a class declaration we provide a mechanism for the programmer to specify each multiple parameter class more precisely The compiler on the other hand is responsible for ensuring that the set of instances that are in scope at any given point in the program is consistent with any declared dependencies For example the following pair of instance declarations cannot appear together in the same scope because they violate the dependency for D even though either one on its own would be acceptable instance D Bool Int where instance D Bool Char where Note also that the following declaration is not allowed even by itself instance D a b where The problem here is that this instance would allow one particular choice of a to be associated with more than one choice for b which contradicts the dependency specified in the definition of D More generally this means that in any instance of the form instance D t s w
393. in the runtime system which could cause a deadlock when scheduling garbage collections has been fixed issue 10545 A bug which could cause compiled programs to loop forever when glibc s iconv implementation gconv wasn t available has been fixed so these programs will now terminate with an error As a result of this change however GHC compiled programs now also specifically recognize ASCII encodings and can function without iconv in these cases This allows statically compiled programs to exist inside an initramfs for example issues 10298 7695 1 6 2 Libraries 1 6 2 1 base Version number 4 8 1 0 was 4 8 0 0 The Lifetime datatype and its constructors are now exported from GHC Event 1 6 2 2 binary Version number 0 7 5 0 was 0 7 3 0 1 6 2 3 Cabal Version number 1 22 4 0 was 1 22 2 0 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 11 327 1 6 2 4 ghc e Several new constructors have been added to the AnnKeywordld datatype in order to fix several problem with GHC s new support for API annotations this should not regress or effect any clients of the GHC APT not using these new features e The source location functionality above required an breaking change to the GHC API Namely the SrcSpans of Ct Loc and TcLclEnv are now RealSrcSpans While usually API changes like this are avoided in bugfix releases it was decided that the benefits offered by the source location fun
394. ing This option causes a warning to be emitted whenever an inner scope value has the same name as an outer scope value i e the inner value shadows the outer one This can catch typographical errors that turn into hard to find bugs e g in the inadvertent capture of what would be a recursive call in f let f id in f The warning is suppressed for names beginning with an underscore For example f x do _ignore lt this _ignore lt that return the other fwarn orphans fwarn auto orphans These flags cause a warning to be emitted whenever the module contains an orphan instance declaration or rewrite rule An instance declaration is an orphan if it appears in a module in which neither the class nor the type being instanced are declared in the same module A rule is an orphan if it is a rule for a function declared in another module A module containing any orphans is called an orphan module The trouble with orphans is that GHC must pro actively read the interface files for all orphan modules just in case their instances or rules play a role whether or not the module s interface would otherwise be of any use See Section 4 7 13 for details The flag Ewarn orphans warns about user written orphan rules or instances The flag fwarn auto orphans warns about automatically generated orphan rules notably as a result of specialising functions for type classes Specia lise or argument values fspec constr fwarn overlapping
395. ing library documentation More packages to install can be obtained from HackageDB Using a package couldn t be simpler if you re using make or GHCi then most of the installed packages will be automatically available to your program without any further options The exceptions to this rule are covered below in Section 4 9 1 Building your own packages is also quite straightforward we provide the Cabal infrastructure which automates the process of configuring building installing and distributing a package All you need to do is write a simple configuration file put a few files in the right places and you have a package See the Cabal documentation for details and also the Cabal libraries Distribution Simple for example 4 9 1 Using Packages GHC only knows about packages that are installed To see which packages are installed use the ghc pkg list command ghc pkg list US at necio package rcon ed Cabal 1 7 4 diray 0 2 One Dase 3 504 3510 base 4 2 0 0 bin package db 0 0 0 0 lgalinaiey 0 5 0 1 bytestring 0 9 1 4 containers 0 2 0 1 clics uo y 1L0 10 2 dph base 0 4 0 dph par 0 4 0 dph prim interface 0 4 0 dph prim par 0 4 0 dph prim seg 0 4 0 dph seq 0 4 0 xtensibl xceptions 0 1 1 0 tai 11 0 cilearcla 4L 4 dl od eine S 12 11 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 67 327 cias rss ON TOMO haskeline 0 6 2 haskel198 1 0 1 0
396. ing GHC_OPT IONS pragma or by specifying fno warn tabs flag e The new fdefer typed holes flag turns typed hole errors into typed hole warnings that produce runtime errors when evaluated The fno warn typed holes flag was repurposed to silence the warnings produced when fdefer typed holes is used As a result it is no longer possible to disable typed holes like it was in GHC 7 8 This only turned a self explanatory error into a cryptic parse error and was thus not very useful For more details consult Section 7 14 and Section 7 16 e A new warning flag fwarn trustworthy safe has been added and is turned on with Wa11 It warns when a module that is compiled with XTrustworthy is actually infered as an XSafe module This lets the module author know that they can tighten their Safe Haskell bounds if desired e The fwarn safe and fwarn unsafe that warn if a module was infered as Safe or Unsafe have been improved to work with all Safe Haskell module types Previously they only worked for unmarked modules where the compiler was infering the modules Safe Haskell type They now work even for modules marked as XTrustworthy or XUnsafe This is useful either to have GHC check your assumptions or to generate a list of reasons easily why a module is regarded as Unsafe For many use cases the new fwarn trustworthy safe flag is better suited than either of these two The Glorious Glasgow Haskell Compilation System User s Guide
397. inspected This is equivalent to setting a breakpoint at every point in the program e Execution can take place in tracing mode in which the evaluator remembers each evaluation step as it happens but doesn t suspend execution until an actual breakpoint is reached When this happens the history of evaluation steps can be inspected e Exceptions e g pattern matching failure and error can be treated as breakpoints to help locate the source of an exception in the program There is currently no support for obtaining a stack trace but the tracing and history features provide a useful second best which will often be enough to establish the context of an error For instance it is possible to break automatically when an exception is thrown even if it is thrown from within compiled code see Section 2 5 6 2 5 1 Breakpoints and inspecting variables Let s use quicksort as a running example Here s the code sore M M qsort a as qsort left a qsort right where left right filter lt a as filter gt a as NANA PE ES OE 3 4 OW Sp te 28 Ail i03 First load the module into GHCi Prelude gt 1 qsort hs 1 of 1 Compiling Main qsort hs interpreted Ok modules loaded Main Main gt Now let s set a breakpoint on the right hand side of the second equation of qsort Main gt break 2 Breakpoint 0 activated at qsort hs 2 15 46 Main gt 5 Note that packages only contain compiled c
398. int locations together with the bodies of functions lambdas case alternatives and binding statements There is normally no breakpoint on a let expression but there will always be a breakpoint on its body because we are usually interested in inspecting the values of the variables bound by the let 2 5 1 2 Listing and deleting breakpoints The list of breakpoints currently enabled can be displayed using show breaks Main gt show breaks LO Wen sort siria Man sort hss 2315 46 To delete a breakpoint use the delete command with the number given in the output from show breaks Main gt delete 0 Main gt show breaks 1 Main qsort hs 2 15 46 To delete all breakpoints at once use delete x 2 5 2 Single stepping Single stepping is a great way to visualise the execution of your program and it is also a useful tool for identifying the source of a bug GHCi offers two variants of stepping Use step to enable all the breakpoints in the program and execute until the next breakpoint is reached Use steplocal to limit the set of enabled breakpoints to those in the current top level function Similarly use stepmodule to single step only on breakpoints contained in the current module For example Main gt step main Stopped at qsort hs 5 7 47 wesc LON The command step expr begins the evaluation of expr in single stepping mode If expr is omitted then it single steps from the current breakpoint steplocal and step
399. ints can also be set by line and optionally column number break line break line column break module line break module line column The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 27 327 When a breakpoint is set on a particular line GHCi sets the breakpoint on the leftmost subexpression that begins and ends on that line If two complete subexpressions start at the same column the longest one is picked If there is no complete subexpression on the line then the leftmost expression starting on the line is picked and failing that the rightmost expression that partially or completely covers the line When a breakpoint is set on a particular line and column GHCi picks the smallest subexpression that encloses that location on which to set the breakpoint Note GHC considers the TAB character to have a width of 1 wherever it occurs in other words it counts characters rather than columns This matches what some editors do and doesn t match others The best advice is to avoid tab characters in your source code altogether see fwarn tabs in Section 4 8 If the module is omitted then the most recently loaded module is used Not all subexpressions are potential breakpoint locations Single variables are typically not considered to be breakpoint locations unless the variable is the right hand side of a function definition lambda or case alternative The rule of thumb is that all redexes are breakpo
400. ion 7 10 2 304 327 Help My program crashed e g a segmentation fault or core dumped If your program has no foreign calls in it and no calls to known unsafe functions such as unsafePerforml0 then a crash is always a BUG in the GHC system except in one case If your program is made of several modules each module must have been compiled after any modules on which it depends unless you use hi boot files in which case these must be correct with respect to the module source For example if an interface is lying about the type of an imported value then GHC may well generate duff code for the importing module This applies to pragmas inside interfaces too If the pragma is lying e g about the arity of a value then duff code may result Furthermore arities may change even if types do not In short if you compile a module and its interface changes then all the modules that import that interface must be re compiled A useful option to alert you when interfaces change is ddump hi diffs It will run diff on the changed interface file before and after when applicable If you are using make GHC can automatically generate the dependencies required in order to make sure that every module is up to date with respect to its imported interfaces Please see Section 4 7 12 If you are down to your last compile before a bug report we would recommend that you add a dcore lint option for extra checking to your
401. ion System User s Guide Version 7 10 2 21 327 e module supports the modifier on modules which opens the full top level scope of a module rather than just its exports e Imports can be removed from the context using the syntax module M The import syntax is cumulative as in a Haskell module so this is the only way to subtract from the scope 2 4 5 4 Qualified names To make life slightly easier the GHCi prompt also behaves as if there is an implicit import qualified declaration for every module in every package and every module currently loaded into GHCi This behaviour can be disabled with the flag fno implicit import qualified 2 4 5 5 module and load It might seem that module import and load add reload do similar things you can use both to bring a module into scope However there is a very important difference GHCi is concerned with two sets of modules e The set of modules that are currently loaded This set is modified by load add and reload and can be shown with show modules e The set of modules that are currently in scope at the prompt This set is modified by import and module and it is also modified automatically after load add and reload as described above The set of modules in scope can be shown with show imports You can add a module to the scope via module or import only if either a it is loaded or b it is a module from a package that GHCi knows about Using mod
402. ion System User s Guide Version 7 10 2 229 327 7 13 4 3 Implicit parameters and polymorphic recursion Consider these two definitions kemik o Lal eee lenl xs let Pacc 0 in len _accl xs len_accl acc len acel res let ace Pace 1 Int in len acel xs ei ss lal A len2 xs let Pacc 0 in len_acc2 xs laa acz gs3 Cace s8 Dar gt Fal lt gt eine len_acc2 acc Lencacez Prize Let face fate Ues mme an den ece2 xs The only difference between the two groups is that in the second group len_acc is given a type signature In the former case len_accl is monomorphic in its own right hand side so the implicit parameter acc is not passed to the recursive call In the latter case because len_acc2 has a type signature the recursive call is made to the polymorphic version which takes acc as an implicit parameter So we get the following results in GHCi Prog gt lenl hello 0 Prog gt len2 hello 5 Adding a type signature dramatically changes the result This is a rather counter intuitive phenomenon worth watching out for 7 13 4 4 Implicit parameters and monomorphism GHC applies the dreaded Monomorphism Restriction section 4 5 5 of the Haskell Report to implicit parameters For example consider i RE Wine NG f v let x 0 in let y x v in La xa in y Since the binding for y falls under the Monomorphism Restriction it is not generalised so the type of y is simply
403. ion System User s Guide Version 7 10 2 9 327 1 5 3 24 Win32 Version number 2 3 1 0 was 2 3 0 1 1 5 3 25 xhtml Version number remained at 3000 2 1 1 5 4 Known bugs For issues dealing with language changes please see the GHC 7 10 Migration Guide on the GHC wiki GHC s LLVM backend does not support LLVM 3 4 issue 9929 On Mac OS X the threaded Garbage Collector currently suffers from a large performance penalty due to a lack of system specific optimization issue 7602 GHC s LLVM backend is currently incompatible with LLVM 3 4 issue 9929 GHCi fails to appropriately load dyn_o files issue 8736 Not all cases of non terminating type level computation with both recursive type families and recursive newtypes are caught This means that GHC might hang but it should do so only when the program is ill typed due to non terminating type level features The bugs are reported as 7788 and 10139 There also remain certain obscure scenarios where the solver for Coercible instances is known to be still incomplete See comments in 10079 1 6 Release notes for version 7 10 2 The 7 10 2 release is a bugfix release with over 70 bug fixes relative to 7 10 1 The major fixes are listed below For the full list with more detail see the GHC 7 10 2 milestone on our bug tracker 1 6 1 GHC The source location of a function s caller can now be made available to the callee as an implicit parameter This will en able bet
404. ion no smaller than head instance C a gt C a where C b b has more occurrences of b than the head instance C b b gt Foo b where The same restrictions apply to instances generated by deriving clauses Thus the following is accepted data MinHeap h a H a h a deriving Show The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 200 327 because the derived instance instance Show a Show h a gt Show MinHeap h a conforms to the above rules A useful idiom permitted by the above rules is as follows If one allows overlapping instance declarations then it s quite conve nient to have a default instance declaration that applies if something more specific does not instance C a where CO oon Detemilie 7 6 3 4 Undecidable instances Sometimes even the rules of Section 7 6 3 3 are too onerous For example sometimes you might want to use the following to get the effect of a class synonym class Cl a C2 a C3 a gt C a where instance Cl a C2 a C3 a gt C a where This allows you to write shorter signatures 2 ak Ca gt instead of E g9 Cle CA a CS a gt The restrictions on functional dependencies Section 7 6 2 are particularly troublesome It is tempting to introduce type variables in the context that do not appear in the head something that is excluded by the normal rules For example class HasConverter a b a gt b where Converti a
405. is Cie Cfblella ewes HORS Basile ic icins D e return e D e io lt e gt gt Ap gt DI D e sp 1 guare e gt gt ya gt DI e D e Let a Y let d in DI e Parallel comprehensions iterate for multiple parallel branches D e COMES ES mzio DI Ov Onl Di Rv RI O gt De Sl Transform comprehensions D e O aca E R EDI l o Il yoy Doiie 3 D e S maca 1 ley 19 ERE E Now gt b Dl Gy 1 gt Nov gt Dl e RI Di Oy NS gt case fmap selQvl ys fmap selQvn ys of Oy gt DIT e E D e Q then group using f R DIe then grouo by le using E E Wy gt b Dl Ov O 1 ys gt case fmap selQvl ys fmap selQvn ys of Ow gt DE RI where Qv is the tuple of variables bound by Q and used subsequently selQvi is a selector mapping Qv to the ith component of Qv Operator Standard binding Expected type return GHC Base cil gt m E2 gt gt GHC Base ml qe s ee S wi 763 ws ES gt gt GHC Base ml El gt 12 162 SIS guard Control Monad cil gt m E2 fmap GHC Base forall a hb lab gt ma gt ab mzip Control Monad Zip toreadll a loo 1 e gt im io im a The comprehension should typecheck when its desugaring would typecheck Monad comprehensions support rebindable syntax Section 7 3 16 Without rebindable syntax the operators from the standard bindin
406. is not really a type because of the record syntax and strictness annotations A type of this form can appear only in a constructor signature Record updates are allowed with GADT style declarations only fields that have the following property the type of the field mentions no existential type variables The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 186 327 e As in the case of existentials declared using the Haskell 98 like record syntax Section 7 4 6 3 record selector functions are generated only for those fields that have well typed selectors Here is the example of that section in GAD Estyle syntax data Counter a where NewCounter _this cl self aa iE 29 self gt self Lhsplay 38 selz gt TO K tag Shi Ral lea Counter fa As before only one selector function is generated here that for tag Nevertheless you can still use all the field names in pattern matching and record construction e Ina GADT style data type declaration there is no obvious way to specify that a data constructor should be infix which makes a difference if you derive Show for the type Data constructors declared infix are displayed infix by the derived show So GHC implements the following design a data constructor declared in a GADT style data type declaration is displayed infix by Show iff a it is an operator symbol b it has two arguments c it has a programmer supplied fixity declaration For exampl
407. is option unless you built GHC yourself 13 2 2 Bugs in GHCi the interactive GHC e GHCi does not respect the default declaration in the module whose scope you are in Instead for expressions typed at the command line you always get the default default type behaviour that is default Int Double It would be better for GHCi to record what the default settings in each module are and use those of the current module whatever that is e On Windows there s a GNU ld BFD bug whereby it emits bogus PE object files that have more than Oxffff relocations When GHCi tries to load a package affected by this bug you get an error message of the form Loading package javavm linking WARNING Overflown relocation field relocs found 30765 The last time we looked this bug still wasn t fixed in the BFD codebase and there wasn t any noticeable interest in fixing it when we reported the bug back in 2001 or so The workaround is to split up the o files that make up your package into two or more o s along the lines of how the base package does it The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 319 327 Chapter 14 Index RTS 96 m 38 r 39 s 39 t 17 39 RTS 96 force 73 global 74 help 46 74 info 47 install signal handlers RTS option 97 interactive 32 ipid 74 machine readable RTS option 100 make 46 47 numeric version 4
408. ised y fields warn when an import fwarn missing declaration does not Amia fnowarn missing import lists explicitly list all the names y import lists brought into scope fwarn missing warn when class methods dynamic fno warn missing methods are undefined y methods fwarn missing warn about top level donam fno warn missing signatures functions without signatures y signatures warn about top level functions without fwarn missing signatures only if they are dynamic fno warn missing exported sigs exported takes precedence y exported sigs over fwarn missing signatures ar warn about polymorphic A E fwarn missing ae fno warn missing f local bindings without dynamic local sigs local sigs signatures fwarn warn when the fno warn monomorphism Monomorphism Restriction dynamic monomorphism restriction is applied restriction fwarn name warn when names are 3 fno warn nam dynamic i shadowing shadowed shadowing warn when the module fno warn orphans fwarn orphans i a contains orphan instance dynamic fno warn auto fwarn auto orphans f A declarations or rewrite rules orphans fwarn fno warn f warn about overlapping A overlapping ee dynamic overlapping patterns P patterns warn if there are tabs in the fwarn tabs dynamic fno warn tabs source file fwarn type warn when defaultin fno warn t 8 dynamic YE defaults The Glorious Glasgow Haskell Compilation System User s Guide Version 7
409. isible earlier and optimisations like fspec constr can create functions with unused arguments which are eliminated by late demand analysis Improvements are modest but so is the cost See notes on the Trac wiki page fliberate case Off by default but enabled by O2 Turn on the liberate case transformation This unrolls recursive function once in its own RHS to avoid repeated case analysis of free variables It s a bit like the call pattern specialiser fspec const r but for free variables rather than arguments fliberate case threshold n Set the size threshold for the liberate case transformation Default 2000 floopification On by default When this optimisation is enabled the code generator will turn all self recursive saturated tail calls into local jumps rather than function calls fmax inline alloc size n Set the maximum size of inline array allocations to n bytes default 128 GHC will allocate non pinned arrays of statically known size in the current nursery block if they re no bigger than n bytes ignoring GC overheap This value should be quite a bit smaller than the block size typically 4096 fmax inline memcpy insn n Inline memcpy calls if they would generate no more than n pseudo instructions default 32 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 81 327 fmax inline memset insns n Inline memset calls if they would generate no more than n pseudo instructions
410. istributed with GHC An InstalledPackagelnfo has a human readable writable syntax The functions parseInstalledPackageInfo and showInstalledPackageInfo read and write this syntax respectively Here s an example of the InstalledPackag eInfo for the unix package S ghc pkg describe unix name unix Wer silos 2 30 1 0 id unix 2 3 1 0 de7803f1la8cd88d2161b29b083c94240 license BSD3 copyright maintainer libraries haskell org srabi nhiem homepage package url description This package gives you access to the set of operating system services standardised by POSIX 1003 1b or the IEEE Portable Operating System Interface for Computing Environments Aaa Sec LOOsS i The package is not supported under Windows except under Cygwin category System author exposed True xposed modules System Posix System Posix DynamicLinker Module System Posix DynamicLinker Prim System Posix Directory System Posix DynamicLinker System Posix Env System Posix Error System Posix Files System Posix IO System Posix Process System Posix Process Internals System Posix Resource System Posix Temp System Posix Terminal System Posix Time System Posix Unistd System Posix User System Posix Signals System Posix Signals Exts System Posix Semaphore System Posix SharedMem hidden modules trusted False ninxonse ehiiess mer L1us che 6 12 1 omise 2 3 140 Liiorary chirss sie alo ciue 6 q 12 iL
411. ith XIncoherent Instances e An instance is overlappable if it has an OVERLAPPABLE or OVERLAPS pragma or if the instance has no pragma and it appears in a module compiled with XOverlappingInstances or if the instance is incoherent e An instance is overlapping if it has an OVERLAPPING or OVERLAPS pragma or if the instance has no pragma and it appears in a module compiled with XOverlappingInstances or if the instance is incoherent Now suppose that in some client module we are searching for an instance of the target constraint C tyl tyn The search works like this e Find all instances I that match the target constraint that is the target constraint is a substitution instance of I These instance declarations are the candidates e Eliminate any candidate IX for which both of the following hold There is another candidate TY that is strictly more specific that is IY is a substitution instance of IX but not vice versa Either IX is overlappable or TY is overlapping This either or design rather than a both and design allow a client to deliberately override an instance from a library without requiring a change to the library e If exactly one non incoherent candidate remains select it If all remaining candidates are incoherent select an arbitary one Otherwise the search fails i e when more than one surviving candidate is not incoherent e If the selected candidate from the previous st
412. itional record syntax se sosie ai aaa at a a Pee eh erdees 163 1 3 12 Therecursive do notation 2 202022882 rr ee AG Ree 163 7 3 12 1 Recursive binding groups 163 T3122 Themdo notation e ke ta nee eai A Pe SEER Se PAE SAS ES 164 7 3 13 Parallel List Comprehensions gt ss 2 2 0 00 0 0 ee 165 7 3 14 Generalised SQL Like List Comprehensions 0 0 00 eee eee ee ee ee 165 7 3 15 Monadcomprehensions se s ecco rea aeta e e a a a e E E OE 167 7 3 16 Rebindable syntax and the implicit Prelude import oaoa e 169 COLT Posthxoperators 2 bah be a a a EHS a A ES 169 73 48 Tuple s ctlons s s po 524884 2455 DS eR SR RRR AES DES ae a a ae eo 170 4 3 19 Lambda case eea ae ee ee ad oe ee ea he de dee E 170 1 3 20 Empty caserallernatives 22 6 46 soe Gy doe ESS Ree a Sees RSS hed S E 171 7 3 21 Multi way if expressions gt gt lt s ee 171 7 3 22 Record field disambiguation oaoa ee 172 7323 Record PUDS a s s s eik a Ee BR e e e eae be Ee a 173 71324 Record wildcards csi 4 44 IEA E A EA E 173 T329 Local Fixity Declarations 0 5 4 stea e e a weet E A ae BRS Ge ees wx 174 7 3 26 Import and export extensions o oo ee 175 7 3 26 1 Hiding things the imported module doesn t export sooo a 175 7 3 26 2 Package qualified imports 2 2 ee ee 175 13 20 3 Sale IMPOTS ios e E AA RE A e Y 176 7 3 26 4 Explicit namespaces in import export e 176 1 3 27 Summary of stolensyntax
413. ity 10 5 of total user 9 1 of total elapsed e The bytes allocated in the heap is the total bytes allocated by the program over the whole run e GHC uses a copying garbage collector by default bytes copied during GC tells you how many bytes it had to copy during garbage collection e The maximum space actually used by your program is the bytes maximum residency figure This is only checked during major garbage collections so it is only an approximation the number of samples tells you how many times it is checked e The bytes maximum slop tells you the most space that is ever wasted due to the way GHC allocates memory in blocks Slop is memory at the end of a block that was wasted There s no way to control this we just like to see how much memory is being lost this way e The total memory in use tells you the peak memory the RTS has allocated from the OS e Next there is information about the garbage collections done For each generation it says how many garbage collections were done how many of those collections were done in parallel the total CPU time used for garbage collecting that generation and the total wall clock time elapsed while garbage collecting that generation e The SPARKS statistic refers to the use of Control Parallel par and related functionality in the program Each spark represents a call to par a spark is converted when it is executed in parallel and a spark is pruned when it is found to be already e
414. iveDo dynamic XNoRecursiveDo notation deprecated Relaxed hecking f XRelaxedPolyRec NAO dynamic XNoRelaxedPolyRec mutually recursive polymorphic functions XRoleAnnotations Enable role annotations dynamic y XNoRoleAnnotations Enable the Safe Haskell XSafe dynamic Safe mode XScopedTypeVariab Enable lexically scoped das XNoScopedTypeVari les type variables y ables X ile D j Ad XN il D j i A IS Enable standalone deriving dynamic eS ing ving XT 1 Haskell Enable Template Haskell dynamic o are P y XNoTemplateHaskell Disable support for XNoTraditionalRec traditional record syntax as XTraditionalRecor dynamic ordSyntax supported by Haskell 98 C dSyntax f x Enable generalised list XNoTransformListC A dynamic XTransformListComp comprehensions omp y Enable the Safe Haskell XTrustworthy dynamic Trustworthy mode XTupleSections Enable tuple sections dynamic XNoTupleSections The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 117 327 Flag Description Static Dynamic Reverse Enable type families Implies XExplicitNam XTypeFamilies espaces dynamic XNoTypeFamilies XKindSignatures and XMonoLocalBinds Enable type operators XTypeOperators Implies XExplicitNam dynamic XNoTypeOperators espaces Enable type sy
415. ize for an individual thread to size bytes If the thread attempts to exceed this limit it will be sent the StackOverflow exception The limit can be disabled entirely by specifying a size of zero This option is there mainly to stop the program eating up all the available memory in the machine if it gets into an infinite loop mn Minimum n of heap which must be available for allocation The default is 3 Msize Default unlimited Set the maximum heap size to size bytes The heap normally grows and shrinks according to the memory requirements of the program The only reason for having this option is to stop the heap growing without bound and filling up all the available swap space which at the least will result in the program being summarily killed by the operating system The maximum heap size also affects other garbage collection parameters when the amount of live data in the heap exceeds a certain fraction of the maximum heap size compacting collection will be automatically enabled for the oldest generation and the F parameter will be reduced in order to avoid exceeding the maximum heap size T t file s file S file machine readable These options produce runtime system statistics such as the amount of time spent executing the program and in the garbage collector the amount of memory allocated the max imum size of the heap and so on The three variants give different levels of detail T collects the data but produces n
416. just make your life a misery and for other people too probably Try to use local disks when linking Because Haskell objects and libraries tend to be large it can take many real seconds to slurp the bits to from a remote filesystem It would be quite sensible to compile on a fast machine using remotely mounted disks then link on a slow machine that had your disks directly mounted Don t derive use Read unnecessarily It s ugly and slow GHC compiles some program constructs slowly We d rather you reported such behaviour as a bug so that we can try to correct it To figure out which part of the compiler is badly behaved the v2 option is your friend The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 149 327 6 2 Faster producing a program that runs quicker The key tool to use in making your Haskell program run faster are GHC s profiling facilities described separately in Chapter 5 There is no substitute for finding where your program s time space is really going as opposed to where you imagine it is going Another point to bear in mind By far the best way to improve a program s performance dramatically is to use better algorithms Once profiling has thrown the spotlight on the guilty time consumer s it may be better to re think your program than to try all the tweaks listed below Another extremely efficient way to make your program snappy is to use library code that has been Seriously
417. kage together with a binary cache of the package data in the file package cache Normally you won t need to look at or modify the contents of a package database directly all management of package databases can be done through the ghc pkg tool see Section 4 9 7 GHC knows about two package databases in particular e The global package database which comes with your GHC installation e g usr lib ghc 6 12 1 package conf ok e A package database private to each user On Unix systems this will be SHOME ghc arch os version package conf d and on Windows it will be something like C Documents And Settings user ghc package conf d The ghc pkg tool knows where this file should be located and will create it if it doesn t exist see Section 4 9 7 2 it used to in GHC 6 4 but not since 6 6 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 70 327 When GHC starts up it reads the contents of these two package databases and builds up a list of the packages it knows about You can see GHC s package table by running GHC with the v flag Package databases may overlap and they are arranged in a stack structure Packages closer to the top of the stack will override shadow those below them By default the stack contains just the global and the user s package databases in that order You can control GHC s package database stack using the following options package db file Add the package
418. ke any other C library with no special accomodations GHC now has support for plugins which modify the type checker This allows external users to interface with GHC and write type checking plugins to solve constraints and equalities generated by the typechecker This feature is experimental and will likely change in the future GHC now has support for a new extension XStaticPointers that allows you to de reference and serialize pointers to known closed expressions This is primarily aimed at making distributed programming via interfaces like Cloud Haskell easier For more see Section 7 21 This feature is experimental and will likely change in the future GHC now has preliminary support for DWARF based debugging when compiling programs with the new g option This will embed DWARF information into the module object files which can then be read by tools like GDB for backtraces or single stepping This feature is highly experimental and will likely change in the future but should still be useful today 1 5 2 Full details 1 5 2 1 Language Implicit parameters of the new base type GHC Stack CallStack are treated specially and automatically solved for the current source location For example if prine petk ge Call lsicecls will print the singleton stack containing the occurrence of stk If there is another Cal1Stack implicit in scope the new location will be appended to the existing stack e g The Glorious Glasgow
419. kell just import Cont rol Concurrent More information on Concurrent Haskell is provided in the documentation for that module Optionally the program may be linked with the threaded option see Section 4 12 6 This provides two benefits e It enables the N RTS option to be used which allows threads to run in parallel on a multiprocessor or multicore machine See Section 4 15 e Ifa thread makes a foreign call and the call is not marked unsafe then other Haskell threads in the program will continue to run while the foreign call is in progress Additionally foreign exported Haskell functions may be called from multiple OS threads simultaneously See Section 8 2 4 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 94 327 The following RTS option s affect the behaviour of Concurrent Haskell programs Cs Sets the context switch interval to s seconds A context switch will occur at the next heap block allocation after the timer expires a heap block allocation occurs every 4k of allocation With C0 or C context switches will occur as often as possible at every heap block allocation By default context switches occur every 20ms 4 15 Using SMP parallelism GHC supports running Haskell programs in parallel on an SMP symmetric multiprocessor There s a fine distinction between concurrency and parallelism parallelism is all about making your program run faster by making use of multiple proces
420. keys of type Int You might wish to tell GHC to use int Lookup instead of genericLookup whenever the latter was called with type Table Int b gt Int gt b It used to be possible to write SPECIALIZE genericLookup Table Int b gt Int gt b intLookup This feature is no longer in GHC but rewrite rules let you do the same thing RULES genericLookup Int genericLookup intLookup This slightly odd looking rule instructs GHC to replace genericLookup by int Lookup whenever the types match What is more this rule does not need to be in the same file as genericLookup unlike the SPECIALIZE pragmas which currently do so that they have an original definition available to specialise It is Your Responsibility to make sure that int Lookup really behaves as a specialised version of genericLookup An example in which using RULES for specialisation will Win Big toDouble Real a gt a gt Double toDouble fromRational toRational RULES toDouble Int toDouble i2d i2d I i D int2Double i uses Glasgow prim op directly The i2d function is virtually one machine instruction the default conversion via an intermediate Rat ional is obscenely expensive by comparison 7 23 7 Controlling what s going on in rewrite rules e Use ddump rules to see the rules that are defined in this module This includes rules generated by the specialisation pass but excludes rule
421. l or in a let or where should be sorted into strongly connected components and then type checked in dependency order Haskell Report Section 4 5 1 As each group is type checked any binders of the group that have an explicit type signature are put in the type environment with the specified poly morphic type and all others are monomorphic until the group is generalised Haskell Report Section 4 5 2 Following a suggestion of Mark Jones in his paper Typing Haskell in Haskell GHC implements a more general scheme If XRelaxedPolyRec is specified the dependency analysis ignores references to variables that have an explicit type signature As a result of this refined dependency analysis the dependency groups are smaller and more bindings will typecheck For example consider E 8 e a gt a gt Boal f x x x g True g Yes gys y lt y IES This is rejected by Haskell 98 but under Jones s scheme the definition for g is typechecked first separately from that for f because the reference to f in g s right hand side is ignored by the dependency analysis Then g s type is generalised to get G gg Ord a gt a gt Bool Now the definition for f is typechecked with this type for g in the type environment The same refined dependency analysis also allows the type signatures of mutually recursive functions to have different contexts something that is illegal in Haskell 98 Section 4 5 2 last sentence With
422. l import syntax is supported including hiding and as clauses The prompt shows the modules that are currently imported but it omits details about hiding as and so on To see the full story use show imports Prelude gt import System IO Prelude System IO gt import Data Map as Map Prelude System IO Map gt show imports import Prelude implicit import System IO import Data Map as Map Prelude System IO Map gt Note that the Prelude import is marked as implicit It can be overridden with an explicit Prelude import just like in a Haskell module With multiple modules in scope especially multiple x form modules it is likely that name clashes will occur Haskell specifies that name clashes are only reported when an ambiguous identifier is used and GHCi behaves in the same way for expressions typed at the prompt 2 4 5 3 Controlling what is in scope with the module command Another way to manipulate the scope is to use the module command whose syntax is this module mod1 modn Using the form of the module commands adds modules to the current scope and removes them Without either or the current scope is replaced by the set of modules specified Note that if you use this form and leave out Prelude an implicit Prelude import will be added automatically The module command provides a way to do two things that cannot be done with ordinary import declarations The Glorious Glasgow Haskell Compilat
423. lStateT 0 do Control Monad State i lt get Control Monad State lift do Control Monad State putot ein WHelslo world Control Monad State joieakione aL Control Monad State Hello World 0 Control Monad State gt During a multiline interaction the user can interrupt and return to the top level prompt Prelude gt do Prelude putStrLn Hello World Prelude C Prelude gt 2 4 4 Type class and other declarations At the GHCi prompt you can also enter any top level Haskell declaration including data type newtype class insta nce deriving and foreign declarations For example Prelude gt data T A B C deriving Eq Ord Show Enum Prelude gt A A B C Prelude gt i T dato A i Defined at lt interactive gt 2 6 instance Enum Defined at lt interactive gt 2 45 instance Eq Defined at lt interactive gt 2 30 instance Ord T Defined at lt interactive gt 2 34 instance Show T Defined at lt interactive gt 2 39 As with ordinary variable bindings later definitions shadow earlier ones so you can re enter a declaration to fix a problem with it or extend it But there s a gotcha when a new type declaration shadows an older one there might be other declarations that refer to the old type The thing to remember is that the old type still exists and these other declarations still refer to the old type However while the old and the new
424. lag is present then go all the way through to linking This table summarises mn a Suffix saying start here Flag saying stop after suffix of output file literate pre processor 1hs hs C pre processor opt hs with cpp E hspp Haskell compiler hs C S he s C compiler opt heor c S sS assembler S C linker other a out Thus a common invocation would be Gre e TOGS to compile the Haskell source file Foo hs to an object file Foo o Note What the Haskell compiler proper produces depends on what backend code generator is used See Section 4 11 for more details Note C pre processing is optional the cpp flag turns it on See Section 4 12 3 for more details Note The option E runs just the pre processing passes of the compiler dumping the result in a file Note The option C is only available when GHC is built in unregisterised mode See Section 4 11 4 for more details 4 5 3 1 Overriding the default behaviour for a file As described above the way in which a file is processed by GHC depends on its suffix This behaviour can be overridden using the x option x suffix Causes all files following this option on the command line to be processed as if they had the suffix suffix For example to compile a Haskell module in the file M my hs use ghc c x hs M my hs The Glorious Glasgow Haskell Compilation System User s Guide Version
425. language extension XMagicHash allows as a postfix modifier to identifiers Thus x is a valid variable and T is a valid type constructor or data constructor The hash sign does not change semantics at all We tend to use variable names ending in for unboxed values or types e g Int but there is no requirement to do so they are just plain ordinary variables Nor does the KMagicHash extension bring anything into scope For example to bring Int into scope you must import GHC Prim see Section 7 2 the KMagicHash extension then allows you to refer to the Int that is now in scope Note that with this option the meaning of x y 0 is changed it defines a function x taking a single argument y to define the operator put a space x y 0 The XMagicHash also enables some new forms of literals see Section 7 2 1 e x has type Char e foo has type Addr e 3 has type Int In general any Haskell integer lexeme followed by a is an Int literal e g Ox3A as well as 32 e 3 has type Word In general any non negative Haskell integer lexeme followed by is a Word e 3 2 has type Float e 3 2 has type Double 7 3 3 Negative literals The literal 123 is according to Haskell98 and Haskell 2010 desugared as negate fromInteger 123 The language extension XNegativeLiterals means that it is instead desugared as fromInteger 123 This can make a difference w
426. language standard This behaviour can be controlled with the DatatypeContext s extension See Section 7 4 2 13 1 1 5 Module system and interface files GHC requires the use of hs boot files to cut the recursive loops among mutually recursive modules as described in Sec tion 4 7 9 This more of an infelicity than a bug the Haskell Report says Section 5 7 Depending on the Haskell implementation used separate compilation of mutually recursive modules may require that imported modules contain additional information so that they may be referenced before they are compiled Explicit type signatures for all exported values may be necessary to deal with mutual recursion The precise details of separate compilation are not defined by this Report 13 1 1 6 Numbers basic types and built in classes Num superclasses The Num class does not have Show or Eq superclasses You can make code that works with both Haskel198 Haskel12010 and GHC by e Whenever you make a Num instance of a type also make Show and Eq instances and e Whenever you give a function instance or class a Num t constraint also give it Show t and Eq t constraints Bits superclasses The Bits class does not have a Num superclasses It therefore does not have default methods for the bit testBit and popCount methods You can make code that works with both Haskell2010 and GHC by e Whenever you make a Bits instance of a type also make a Num instance and The Glorious
427. ldings unfoldings functions Turn on the float in ffloat in transformation Implied by dynamic fno float in 0 Turn on full laziness ffull laziness floating bindings dynamic fno full laziness outwards Implied by o Allow worker wrapper to convert a function closure ffun to thunk into a thunk if the function dynamic fno fun to thunk does not use any of its arguments Off by default The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 122 327 Flag Description Static Dynamic Reverse fignore asserts Ignore assertions in the source Implied by O dynamic fno ignore asserts fignore interface pragmas Ignore pragmas in interface files Implied by 00 only dynamic fno ignore interface pragmas flate dmd anal Run demand analysis again at the end of the simplification pipeline dynamic fno late dmd anal fliberate cas Turn on the liberate case transformation Implied by 02 dynamic fno liberate case fliberate cas threshold n Set the size threshold for the liberate case transformation to n default 2000 dynamis fno liberat case threshold floopification Turn saturated self recursive tail calls into local jumps in the generated assembly Implied by 0 dynamic fno loopification fmax inlin alloc size n Set the maximum size of inline array allocations to n b
428. le i e when using c 4 19 10 Interactive mode options Section 2 9 Flag Description Static Dynamic Reverse Disable reading of ghci ignore dot ghci dynamic files eine Read additional ghci dynamic i files Break on uncaught fno break on fbreak on error dynamic exceptions and errors error fbreak on Break on any exception fno break on oe dynamic exception thrown exception koe Set the number of entries fghci hist size n Buba be ary dynamic default is 50 fprint evld with Enable usage of Show i fno print evld a a dynamic show instances 1n print with show fprint bind Turn on printing of binding die fno print bind result results in GHCi y result fno print bind Turn off printing of binding dynamig g contents contents in GHCi The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 112 327 Flag Description Static Dynamic Reverse fno implicit Turn off implicit qualified l import gualified import of everything in dynamic cd GHCi Select the function to use interactive print for printing evaluated dynamic expressions in GHCi 4 19 11 Packages Section 4 9 Flag Description Static Dynamic Reverse s Compile to be part of this package key P package dynamic package P Expose package P dynamic set hide all packages Hide all packages by default dynamic hide package name Hide package P dynamic set
429. le of thumb is that if the modules of the package were compiled with sp1it objs then building the HSfoo o is worthwhile because it saves time when loading the package into GHCi Without split objs there is not much difference in load time between the o and a libraries so it is better to save the disk space and only keep the a around In a GHC distribution we provide o files for most packages except the GHC package itself The HSfoo o file is built by Cabal automatically use disable library for ghci to disable it To build one manually the following GNU Id command can be used iil whole archiv OMG HOCH Lio a replace whole archive with al1_load on MacOS X When building the package as shared library GHC can be used to perform the link step This hides some of the details out the underlying linker and provides a common interface to all shared object variants that are supported by GHC DLLs ELF DSOs and Mac OS dylibs The shared object must be named in specific way for two reasons 1 the name must contain the GHC compiler version so that two library variants don t collide that are compiled by different versions of GHC and that therefore are most likely incompatible with respect to calling conventions 2 it must be different from the static name otherwise we would not be able to control the linker as precisely as necessary to make the st at ic dynamic flags work see Section 4 12 6 ghc shared 1ibHSfoo 1 0 ghcGHCVe
430. lenames Question How does GHC find the filename which contains module M Answer it looks for the file M hs or M 1hs This means that for most modules the module name must match the filename If it doesn t GHCi won t be able to find it There is one exception to this general rule when you load a program with load or specify it when you invoke ghci you can give a filename rather than a module name This filename is loaded if it exists and it may contain any module you like This is particularly convenient if you have several Main modules in the same directory and you can t call them all Main hs The search path for finding source files is specified with the i option on the GHCi command line like so or it can be set using the set command from within GHCi see Section 282 One consequence of the way that GHCi follows dependencies to find modules to load is that every module must have a source file The only exception to the rule is modules that come from a package including the Prelude and standard libraries such as IO and Complex If you attempt to load a module for which GHCi can t find a source file even if there are object and interface files for the module you ll get an error message 2 2 2 Making changes and recompilation If you make some changes to the source code and want GHCi to recompile the program give the reload command The program will be recompiled as necessary with GHCi doing its best to avoid actually
431. les There s rarely a speed disadvantage modern machines will use the same floating point unit for both With Doubles you are much less likely to hang yourself with numerical errors One time when Float might be a good idea is if you have a lot of them say a giant array of Floats They take up half the space in the heap compared to Doubles However this isn t true on a 64 bit machine Use unboxed arrays UArray GHC supports arrays of unboxed elements for several basic arithmetic element types including Int and Char see the Data Array Unboxed library for details These arrays are likely to be much faster than using standard Haskell 98 arrays from the Data Array library Use a bigger heap If your program s GC stats S RTS option indicate that it s doing lots of garbage collection say more than 20 of execution time more memory might help with the M lt size gt or A lt size gt RTS options see Section 4 17 3 6 3 Smaller producing a program that is smaller Decrease the go for it threshold for unfolding smallish expressions Give a funfolding use threshold0 option for the extreme case Only unfoldings with zero cost should proceed Warning except in certain specialised cases like Happy parsers this is likely to actually increase the size of your program because unfolding generally enables extra simplifying optimisations to be performed Avoid Read Use strip on your executables 6 4 Thrift
432. les Modules reexported by this package This list takes the form of pkg OldName as NewName A orig pkg 0 1 HASH the first portion of the string is the user written reexport specification possibly omitting the package qualifier and the renaming while the parenthetical is the original package which exposed the module under are particular name Reexported modules have a relaxed overlap constraint it s permissible for two packages to reexport the same module as the same name if the reexported moduleis identical The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 77 327 trusted bool Whether the package is trusted or not import dirs string list A list of directories containing interface files hi files for this package If the package contains profiling libraries then the interface files for those library modules should have the suffix p_hi So the package can contain both normal and profiling versions of the same library without conflict see also library_dirs below library dirs string list A list of directories containing libraries for this package hs libraries string list A list of libraries containing Haskell code for this package with the a or d11 suffix omitted When packages are built as libraries the 1ib prefix is also omitted For use with GHCi each library should have an object file too The name of the object file does not have a 1ib prefix and has the normal object suffix for yo
433. level albeit prefixed with a quote data HList x gt x where EN ES lt f HComs Sc gt kise A T data Tuple x x gt where Mpls 28 e gt lp gt Muple a 19 foo 3 Biase ll foo0 HNil Tool 28 llbisiwe Y me tool Hcons Sss ime ANTI foo2 se BList Mrhar Bool foo2 Note the declaration for HCons also requires XTypeOperators because of infix type operator For type level lists of two or more elements such as the signature of 002 above the quote may be omitted because the meaning is unambiguous But for lists of one or zero elements as in foo0 and fool the quote is required because the types and Int have existing meanings in Haskell 7 9 5 Promoting existential data constructors Note that we do promote existential data constructors that are otherwise suitable For example consider the following data Ex where MERO ae a gt Ex Both the type Ex and the data constructor MKEx get promoted with the polymorphic kind MkEx forall k k gt Ex Somewhat surprisingly you can write a type family to extract the member of a type level existential type family UnEx ex EZEK type instance UnEx MkEx x x The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 222 327 At first blush UnEx seems poorly kinded The return kind k is not mentioned in the arguments and thus it would seem that an i
434. ling via C so this checking is not performed The change was made for compatibility with the native code generator fasm and to comply strictly with the FFI specification which requires that FFI calls are not subject to macro expansion and other CPP conversions that may be applied when using C header files This approach also simplifies the inlining of foreign calls across module and package boundaries there s no need for the header file to be available when compiling an inlined version of a foreign call so the compiler is free to inline foreign calls in any context The include option is now deprecated and the include files field in a Cabal package specification is ignored 8 2 3 Memory Allocation The FFI libraries provide several ways to allocate memory for use with the FFI and it isn t always clear which way is the best This decision may be affected by how efficient a particular kind of allocation is on a given compiler platform so this section aims to shed some light on how the different kinds of allocation perform with GHC alloca and friends Useful for short term allocation when the allocation is intended to scope over a given IO computation This kind of allocation is commonly used when marshalling data to and from FFI functions In GHC alloca is implemented using MutableByteArray so allocation and deallocation are fast much faster than C s malloc free but not quite as fast as stack allocation in C Use alloca whenever you
435. lled by the NondecreasingIndentation extension GHC doesn t do the fixity resolution in expressions during parsing as required by Haskell 98 but not by Haskell 2010 For example according to the Haskell 98 report the following expression is legal let x 42 in x 42 True The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 315 327 and parses as let x 42 in x 42 Tru because according to the report the let expression extends as far to the right as possible Since it can t extend past the second equals sign without causing a parse error is non fix the let expression must terminate there GHC simply gobbles up the whole expression parsing like this let x 42 in x 42 True 13 1 1 3 Expressions and patterns In its default mode GHC makes some programs slightly more defined than they should be For example consider f lal gt AO E cerros Sog f x xs lv gt v mea pelage E U ecer True This should call error but actually prints True Reason GHC eta expands f to lal gt la gt Ip E f v error urk ARIS This improves efficiency slightly but significantly for most programs and is bad for only a few To suppress this bogus optimi sation use fpedantic bottoms 13 1 1 4 Declarations and bindings In its default mode GHC does not accept datatype contexts as it has been decided to remove them from the next version of the
436. lls tcPluginSolve This function is provided with the current set of con straints and should return a TcPluginResult that indicates whether a contradiction was found or progress was made If the plugin solver makes progress GHC will re start the constraint solving pipeline looping until a fixed point is reached e Finally GHC calls t cPluginStop after constraint solving is finished allowing the plugin to dispose of any resources it has allocated e g terminating the SMT solver process Plugin code runs in the TcP luginM monad which provides a restricted interface to GHC API functionality that is relevant for typechecker plugins including IO and reading the environment If you need functionality that is not exposed in the TcPlug inM module you can use unsafeTcPluginTcM TcM a gt TcPluginM a but are encouraged to contact the GHC team to suggest additions to the interface Note that TcP1uginM can perform arbitrary IO via tcPluginIO 10 a gt TcPluginM a although some care must be taken with side effects particularly in tcP1uginSolve In general it is up to the plugin author to make sure that any IO they do is safe 9 3 4 1 Constraint solving with plugins The key component of a typechecker plugin is a function of type TcPluginSolver like this solve ks Gel gt Cel gt Gel gt weP weal mates suule solve givens deriveds wanteds This function will be invoked at two points in the constraint solving process after simplif
437. lly propagate this information back into the instance head and make that instance declaration apply only to type of kind as opposed to types of any kind However GHC does not do this In short GHC does not propagate kind information from the members of a class instance declaration into the instance declaration head This lack of kind inference is simply an engineering problem within GHC but getting it to work would make a substantial change to the inference infrastructure and it s not clear the payoff is worth it If you want to restrict b s kind in the instance above just use a kind signature in the instance head 7 9 Datatype promotion This section describes data type promotion an extension to the kind system that complements kind polymorphism It is enabled by XDataKinds and described in more detail in the paper Giving Haskell a Promotion which appeared at TLDI 2012 7 9 1 Motivation Standard Haskell has a rich type language Types classify terms and serve to avoid many common programming mistakes The kind language however is relatively simple distinguishing only lifted types kind type constructors eg kind x gt gt x and unlifted types Section 7 2 1 In particular when using advanced type system features such as type families Section 7 7 or GADTs Section 7 4 8 this simple kind system is insufficient and fails to prevent simple errors Consider the example of type level natural numbers and length ind
438. lly quantifies them For example the following pairs are equivalent E 9k gt El 88 corall as E gt g x a let la 28 gt lo gt Io lak y y Noe g x a let EEE O IA gt 9 gt 9 lol Se Y Y SMM oo Notice that GHC does not find the innermost possible quantification point For example E Sk la gt a gt bat MEANS E 8 forall a a gt a gt Dac ENON ts rorall a a gt gt IME The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 234 327 G gs Oe a gt a gt a gt Mine MEANS the illegal type G gg corall cs O ARAS ENE NOT G gs EEC AI cs Ozil a gt a gt a gt Imne The latter produces an illegal type which you might think is silly but at least the rule is simple If you want the latter type you can write your for alls explicitly Indeed doing so is strongly advised for rank 2 types 7 13 7 Impredicative polymorphism GHC supports impredicative polymorphism enabled with XImpredicativeTypes This means that you can call a poly morphic function at a polymorphic type and parameterise data structures over polymorphic types For example f Maybe forall a a gt a gt Maybe Int Char US E Just o Il A Cito f Nothing Nothing Notice here that the Maybe type is parameterised by the polymorphic type forall a a gt a The technical details of this extension are described in the paper B
439. lo olleh Prelude gt 5 5 10 2 4 1 I O actions at the prompt GHCi does more than simple expression evaluation at the prompt If you enter an expression of type IO a for some a then GHCi executes it as an IO computation Prelude gt hello hello Prelude gt putStrLn hello hello The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 16 327 This works even if the type of the expression is more general provided it can be instantiated to IO a For example Prelude gt return True True Furthermore GHCi will print the result of the I O action if and only if e The result type is an instance of Show e The result type is not For example remembering that putStrLn String gt IO Prelude gt putStrLn hello hello Prelude gt do putStrLn hello return yes hello yes 2 4 2 Using do notation at the prompt GHCi actually accepts statements rather than just expressions at the prompt This means you can bind values and functions to names and use them in future expressions or statements The syntax of a statement accepted at the GHCi prompt is exactly the same as the syntax of a statement in a Haskell do expression However there s no monad overloading here statements typed at the prompt must be in the IO monad Prelude gt x lt return 42 Prelude gt print x 42 Prelude gt The statement x lt return 42 means execute return 42 in the IO mona
440. loaded into GHCi or be a member of a package If module is omitted the most recently loaded module is used Like all other GHCi commands the output is always displayed in the current GHCi scope Section 2 4 5 There are two variants of the browse command e Ifthe symbol is placed before the module name then all the identifiers in scope in module rather that just its exports are shown The x form is only available for modules which are interpreted for compiled modules including modules from pack ages only the non x form of browse is available e Data constructors and class methods are usually displayed in the context of their data type or class declaration However if the symbol is appended to the command thus browse they are listed individually The form also annotates the listing with comments giving possible imports for each group of entries Here is an example Prelude gt browse Data Maybe not currently imported Data Maybe catMaybes Maybe a gt a Data Maybe fromJust Maybe a gt a Data Maybe fromMaybe a gt Maybe a gt a Data Maybe isJust Maybe a gt Bool Data Maybe isNothing Maybe a gt Bool Data Maybe listToMaybe a gt Maybe a Data Maybe mapMaybe a gt Maybe b gt a gt b Data Maybe maybeToList Maybe a gt a imported via Prelude Just a gt Maybe a data Maybe a Nothing Just a Nothing Maybe a MANOS o gt la gt
441. losing lambdas in the hope they will be thereby be computed less often See Let floating moving bindings to give faster programs ICFP 96 Full laziness increases sharing which can lead to increased memory residency NOTE GHC doesn t implement complete full laziness When optimisation in on and fno full laziness is not given some transformations that increase sharing are performed such as extracting repeated computations from a loop These are the same transformations that a fully lazy implementation would do the difference is that GHC doesn t consis tently apply full laziness so don t rely on it ffun to thunk Worker wrapper removes unused arguments but usually we do not remove them all lest it turn a function closure into a thunk thereby perhaps creating a space leak and or disrupting inlining This flag allows worker wrapper to remove all value lambdas Off by default fignore asserts On by default Causes GHC to ignore uses of the function Exception assert in source code in other words rewriting Exception assert p e toe see Section 7 20 fignore interface pragmas Tells GHC to ignore all inessential information when reading interface files That is even if M hi contains unfolding or strictness information for a function GHC will ignore that information flate dmd anal Run demand analysis again at the end of the simplification pipeline We found some opportunities for discovering strictness that were not v
442. meters the default is that parameters must always be explicit propagated With implicit parameters the default is to always propagate them The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 228 327 An implicit parameter type constraint differs from other type class constraints in the following way All uses of a particular implicit parameter must have the same type This means that the type of x x is x a gt a a andnot x a x b gt a b as would be the case for type class constraints You can t have an implicit parameter in the context of a class or instance declaration For example both these declarations are illegal class x Int gt C a where instance x a gt Foo a where Reason exactly which implicit parameter you pick up depends on exactly where you invoke a function But the invocation of instance declarations is done behind the scenes by the compiler so it s hard to figure out exactly where it is done Easiest thing is to outlaw the offending types Implicit parameter constraints do not cause ambiguity For example consider f e 28 Ed gt lia gt Dome f n mn length x g Read a Show a gt String gt String g s show read s Here g has an ambiguous type and is rejected but f is fine The binding for x at s call site is quite unambiguous and fixes the type a 7 13 4 2 Implicit parameter bindings An implicit paramete
443. mit interfac pragmas Don t generate interface pragmas Implied by 00 only dynamic fno omit interface pragmas fomit yields Omit heap checks when no allocation is being performed dynamic fno omit yields fpedantic bottoms Make GHC be more precise about its treatment of bottom but see also fno state hack In particular GHC will not eta expand through a case expression dynamic fno pedantic bottoms fregs graph Use the graph colouring register allocator for register allocation in the native code generator Implied by 02 dynamic fno regs graph fregs iterativ Use the iterative coalescing graph colouring register allocator in the native code generator dynamic fno regs iterative fsimplifier phases n Set the number of phases for the simplifier default 2 Ignored with 00 dynamic fsimpl tick factor n Set the percentage factor for simplifier ticks default 100 dynamic fspec constr Turn on the SpecConstr transformation Implied by 02 dynamic fno spec constr fspec constr count n Set to n default 3 the maximum number of specialisations that will be created for any one function by the SpecConstr transformation dynamic fno spec constr count fspec constr threshold n Set the size threshold for the SpecConstr transformation to n default 2000 dynamic fno spec co
444. module work similarly The list command is particularly useful when single stepping to see where you currently are aso seo ANA Mc As 4 5 maia galne ES O lep 4r WO 3 1 23 ti Tal 6 asort hs 5 7 47 Main gt In fact GHCi provides a way to run a command when a breakpoint is hit so we can make it automatically do list The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 28 327 Sort sesos 72471 Mains sser Stog liste qsort hs 5 7 47 Main gt step Stopped at qsort hs 5 14 46 result Integer 4 5 mata jorge ES O lep 4r OW 5p 1 23 tia Tal 6 asort hs 5 14 46 Main gt 2 5 3 Nested breakpoints When GHCi is stopped at a breakpoint and an expression entered at the prompt triggers a second breakpoint the new breakpoint becomes the current one and the old one is saved on a stack An arbitrary number of breakpoint contexts can be built up in this way For example sortean sao Maan SS oO E AS stoppedtattas orcas OI SS result al ds oras AO Solo ile Main While stopped at the breakpoint on line 2 that we set earlier we started a new evaluation with step qsort 1 3 This new evaluation stopped after one step at the definition of gsort The prompt has changed now prefixed with to indicate that there are saved breakpoints beyond the current one To see the stack of contexts use show context qsort hs 1 0 3 55 Main gt show
445. moves the burden of placing explicit rec blocks in the code Unlike an ordinary do expression in which variables bound by statements are only in scope for later statements variables bound in an mdo expression are in scope for all statements of the expression The compiler then automatically identifies minimal mutually recursively dependent segments of statements treating them as if the user had wrapped a rec qualifier around them The definition is syntactic e A generator g depends on a textually following generator g if g defines a variable that is used by g or g textually appears between g and g where g depends on g e A segment of a given mdo expression is a minimal sequence of generators such that no generator of the sequence depends on an outside generator As a special case although it is not a generator the final expression in an mdo expression is considered to form a segment by itself Segments in this sense are related to strongly connected components analysis with the exception that bindings in a segment cannot be reordered and must be contiguous Here is an example mdo expression and its translation to rec blocks mado E lt ejsuClaelje gt do a lt getChar a doy lt E aa 2 rec 1 b lt rr aAa oc lt E be Tes boa Bo lt la a lo EAS CES ode pg wee e lt gt e cle Ae lt ganz H Pes Gan p eutEhas B put Cneu The Glorious Glasgow Haskell Compilatio
446. mpiler NB it is extremely important you use seq or a bang pattern on the SPEC argument In particular after inlining this will expose f to the loop body directly allowing heavy specialisation over the recursive cases fspec constr count n Set the maximum number of specialisations that will be created for any one function by the SpecConstr transformation default 3 fspec constr threshold n Set the size threshold for the SpecConstr transformation default 2000 fspecialise On by default Specialise each type class overloaded function defined in this module for the types at which it is called in this module Also specialise imported functions that have an INLINABLE pragma Section 7 22 6 2 for the types at which they are called in this module fstatic argument transformation Turn on the static argument transformation which turns a recursive function into a non recursive one with a local recursive loop See Chapter 7 of Andre Santos s PhD thesis fstrictness On by default Switch on the strictness analyser There is a very old paper about GHC s strictness analyser Measuring the effectiveness of a simple strictness analyser but the current one is quite a bit different The strictness analyser figures out when arguments and variables in a function can be treated strictly that is they are always evaluated in the function at some point This allow GHC to apply certain optimisations such as unboxing that other
447. mplementation when declaring a class class Enum a where enum a enum The type of the enum method is a and this is also the type of the default method You can lift this restriction and give another type to the default method using the flag KDefaultSignatures For instance if you have written a generic implementation of enumeration in a class GEnum with method genum in terms of GHC Generics you can specify a default method that uses that generic implementation class Enum a where enum a default enum Generic a GEnum Rep a gt a enum map to genum The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 194 327 We reuse the keyword default to signal that a signature applies to the default method only when defining instances of the Enum class the original type a of enum still applies When giving an empty instance however the default implementation map to genum is filled in and type checked with the type Generic a GEnum Rep a gt a We use default signatures to simplify generic programming in GHC Section 7 26 7 6 1 5 Nullary type classes Nullary no parameter type classes are enabled with XMultiTypeClasses historically they were enabled with the now deprecated XNullaryTypeClasses Since there are no available parameters there can be at most one instance of a nullary class A nullary type class might be used to document some assumption in
448. mwindres Section 4 12 1 and optwindres Section 4 12 2 fno shared implib DLLs on Windows are typically linked to by linking to a corresponding 1ib or d11 a the so called import library GHC will typically generate such a file for every DLL you create by compiling in shared mode However sometimes you don t want to pay the disk space cost of creating this import library which can be substantial it might require as much space as the code itself as Haskell DLLs tend to export lots of symbols As long as you are happy to only be able to link to the DLL using GetProcAddress and friends you can supply the fno shared implib flag to disable the creation of the import library entirely dylib install name path On Darwin OS X dynamic libraries are stamped at build time with an install name which is the ultimate install path of the library file Any libraries or executables that subsequently link against it will pick up that path as their runtime search location for it By default ghc sets the install name to the location where the library is built This option allows you to override it with the specified file path It passes install_name to Apple s linker Ignored on other platforms rdynamic This instructs the linker to add all symbols not only used ones to the dynamic symbol table Currently Linux and Windows MinGW32 only This is equivalent to using opt 1 rdynamic on Linux and opt 1 xport all symbols on Windows
449. n For an example we have a program called Recip hs which computes exact decimal representations of reciprocals with recurring parts indicated in brackets reciproca ME Ibai gt Susie iinic Teclijprocal im m gt l 0 g VA 2 Chigntes ESCUE otherwise error attempting to compute reciprocal of number lt 1 where digits recur divide n 1 ciaee 22 Dale gt ot gt mel gt Siciealine ite dildos e len cs AAA O Stones r 0 show q 0 Pas 2 0 show q digits recur where Ci 12 SO cuore sa digits recur divide n r c cs position 22 ae gt iac gt Tat position n x xs n x 1 otherwise 1 position n xs SHOWER SUPE AS ENS showRecip n 1 show n 1 0 acia cl else tele jo el ar 0 apap cleoja je cl apap YY where p length d r The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 144 327 AA reciproca liim main do number lt readLn putStrLn showRecip number main HPC instrumentation is enabled with the fhpc flag ghc fhpc Recip hs GHC creates a subdirectory hpc in the current directory and puts HPC index mix files in there one for each module compiled You don t need to worry about these files they contain information needed by the hpc tool to generate the coverage data for compiled modules after the program is run Recip 1 3 ORO Running the program generates
450. n eg hr in the example above but there is no limit on the number of further restrictions that may be applied All the options may be combined with one exception GHC doesn t currently support mixing the hr and hb options There are three more options which relate to heap profiling isecs Set the profiling sampling interval to secs seconds the default is 0 1 second Fractions are allowed for example i0 2 will get 5 samples per second This only affects heap profiling time profiles are always sampled with the frequency of the RTS clock See Section 5 3 for changing that xt Include the memory occupied by threads in a heap profile Each thread takes up a small area for its thread state in addition to the space allocated for its stack stacks normally start small and then grow as necessary This includes the main thread so using xt is a good way to see how much stack space the program is using Memory occupied by threads and their stacks is labelled as TSO and STACK respectively when displaying the profile by closure description or type description Lnum Sets the maximum length of a cost centre stack name in a heap profile Defaults to 25 5 4 2 Retainer Profiling Retainer profiling is designed to help answer questions like why is this data being retained We start by defining what we mean by a retainer A retainer is either the system stack an unevaluated closure thunk or an explicitly mutabl
451. n ExNumPat Show b gt Num a Eq a gt b gt Ta pattern ExNumPat x MkT 42 x 12 8 VC ay ING E Se MIS E gt Siciesline f2 ExNumPat x show x Here 1 does not use pattern synonyms To match against the numeric pattern 42 requires the caller to satisfy the constraints Num a Eq a so they appear in 1 s type The call to show generates a Show b constraint where b is an existentially type variable bound by the pattern match on Mk T But the same pattern match also provides the constraint Show b see MkT s type and so all is well Exactly the same reasoning applies to ExNumPat matching against ExNumPat requires the constraints Num a Eq a and provides the constraint Show b Note also the following points e In the common case where CReg is empty it can be omitted altogether e You may specify an explicit pattern signature as we did for ExNumP at above to specify the type of a pattern just as you can for a function As usual the type signature can be less polymorphic than the inferred type For example Inferred type would be a gt a eheiceien Saline lee eatie go Gi a gt ley el pattern SinglePair x x e The GHCi info command shows pattern types in this format The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 162 327 For a bidirectional pattern synonym a use of the pattern synonym as an expression has the t
452. n System User s Guide Version 7 10 2 165 327 Note that a given mdo expression can cause the creation of multiple rec blocks If there are no recursive dependencies mdo will introduce no rec blocks In this latter case an mdo expression is precisely the same as a do expression as one would expect In summary given an mdo expression GHC first performs segmentation introducing rec blocks to wrap over minimal recursive groups Then each resulting rec is desugared using a call to Control Monad Fix mfix as described in the previous section The original mdo expression typechecks exactly when the desugared version would do so Here are some other important points in using the recursive do notation e It is enabled with the flag XRecursiveDo or the LANGUAGE RecursiveDo pragma The same flag enables both mdo notation and the use of rec blocks inside do expressions e rec blocks can also be used inside mdo expressions which will be treated as a single statement However it is good style to either use mdo or rec blocks in a single expression e If recursive bindings are required for a monad then that monad must be declared an instance of the MonadFix class e The following instances of MonadF ix are automatically provided List Maybe IO Furthermore the Control Monad ST and Control Monad ST Lazy modules provide the instances of the MonadFix class for Haskell s internal state monad strict and lazy respectively e Like l
453. n duplicate warn when an entity is dynamic fno warn exports exported multiple times duplicate exports The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 118 327 defaults happens Flag Description Static Dynamic Reverse f warn when a hi file in the f fwarn hi fno warn hi current directory shadows a dynamic shadowing shadowing library warn about uses of Prelude numeric conversions that i es P A fno warn fwarn identities are probably the identity dynamic i M identities and hence could be omitted fwarn implicit warn when the Prelude is dynamic fno warn prelude implicitly imported y implicit prelude P fno warn fwarn incomplete warn when a pattern match dynamic incomplete patterns could fail patterns warn when a pattern match fno warn fwarn incomplete E F in a lambda expression or dynamic incomplete uni uni patterns ee pattern binding could fail patterns F fno warn fwarn incomplete warn when a record update a f p dynamic incomplete record record updates could fail updates deprecated warn when a E ira attern binding looks laz dynamic OY unlifted bindings P 8 y y unlifted bindings but must be strict fwarn missing warn when fields of a ds fno warn missing fields record are uninitial
454. n of insert makes available an Eq a context In implementation terms the MkSet constructor has a hidden field that stores the Eq a dictionary that is passed to MkSet so when pattern matching that dictionary becomes available for the right hand side of the match In the example the equality dictionary is used to satisfy the equality constraint generated by the call to elem so that the type of insert itself has no Eq constraint For example one possible application is to reify dictionaries data NumInst a where MkNumInst Num a gt NumInst a E SN Us me intInst MkNumInst Plus e4 Numinest a gt a gt a gt plus MkNumInst p 4 pPp q The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 184 327 Here a value of type NumInst a is equivalent to an explicit Num a dictionary All this applies to constructors declared using the syntax of Section 7 4 6 2 For example the NumInst data type above could equivalently be declared like this data NumInst a Num a gt MkNumInst NumInst a Notice that unlike the situation when declaring an existential there is no forall because the Num constrains the data type s universally quantified type variable a A constructor may have both universal and existential type variables for example the following two declarations are equivalent data Tl a forall b Num a Eq b gt MkT1 ab data T2 a where MIA ge Num e Be o gt
455. n the compiler ghc make XQuasiQuotes Main hs o main Run main and here is your output main 3 de 7 18 Arrow notation Arrows are a generalization of monads introduced by John Hughes For more details see e Generalising Monads to Arrows John Hughes in Science of Computer Programming 37 pp67 111 May 2000 The paper that introduced arrows a friendly introduction motivated with programming examples e A New Notation for Arrows Ross Paterson in ICFP Sep 2001 Introduced the notation described here e Arrows and Computation Ross Paterson in The Fun of Programming Palgrave 2003 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 251 327 e Programming with Arrows John Hughes in 5th International Summer School on Advanced Functional Programming Lec ture Notes in Computer Science vol 3622 Springer 2004 This paper includes another introduction to the notation with practical examples e Type and Translation Rules for Arrow Notation in GHC Ross Paterson and Simon Peyton Jones September 16 2004 A terse enumeration of the formal rules used extracted from comments in the source code The arrows web page athttp www haskell org arrows With the XArrows flag GHC supports the arrow notation described in the second of these papers translating it using com binators from the Control Arrow module What follows is a brief introduction to the
456. n the same module as the SPECIALIZE pragma or if they are INLINABLE and so on transitively The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 265 327 T You can add phase control Section 7 22 6 5 to the RULE generated by a SPECIALIZE pragma just as you can if you write a RULE directly For example SPECIALIZE 0 hammeredLookup Widget value gt Widget gt value generates a specialisation rule that only fires in Phase O the final phase If you do not specify any phase control in the SPECIALIZE pragma the phase control is inherited from the inline pragma if any of the function For example TOO g2 NUM a gt a gt a TOO pa nlollalnes NOINLINE 0 foo 7 SPC da Gree SE Mois gt lote ip The NOINLINE pragma tells GHC not to inline foo until Phase 0 and this property is inherited by the specialisation RULE which will therefore only fire in Phase 0 The main reason for using phase control on specialisations is so that you can write optimisation RULES that fire early in the compilation pipeline and only then specialise the calls to the function If specialisation is done too early the optimisation rules might fail to fire The type in a SPECIALIZE pragma can be any type that is less polymorphic than the type of the original function In concrete terms if the original function is f
457. n too place If you add dppr debug you get more detailed information ddump if trace Make the interface loader be real chatty about what it is up to ddump tc trace Make the type checker be real chatty about what it is up to ddump vt trace Make the vectoriser be real chatty about what it is up to ddump rn trace Make the renamer be real chatty about what it is up to ddump rn stats Print out summary of what kind of information the renamer had to bring in dverbose core2core dverbose stg2stg Show the output of the intermediate Core to Core and STG to STG passes respectively Lots of output So when we re really desperate o ghc noC O ddump simpl dverbose core2cor dcore lint Foo hs dshow passes Print out each pass name as it happens ddump core stats Print a one line summary of the size of the Core program at the end of the optimisation pipeline dfaststring stats Show statistics for the usage of fast strings by the compiler dppr debug Debugging output is in one of several styles Take the printing of types for example In the user style the default the compiler s internal ideas about types are presented in Haskell source level syntax insofar as possible In the debug style which is the default for debugging output the types are printed in with explicit foralls and variables have their unique id attached so you can check for things that look the same but aren t This
458. n usr include 12 5 2 The problem GHC by default no longer depends on cygwin but is a native windows program It is built using mingw and it uses mingw s ghc while compiling your Haskell sources even if you call it from cygwin s bash but what matters here is that just like any other normal windows program neither GHC nor the executables it produces are aware of cygwin s pretended unix hierarchy GHC will happily accept either or V as path separators but it won t know where to find home joe Main hs or bin bash or the like This causes all kinds of fun when GHC is used from within cygwin s bash or in make sessions running under cygwin 12 5 3 Things to do Don t use absolute paths in make configure amp co if there is any chance that those might be passed to GHC or to GHC compiled programs Relative paths are fine because cygwin tools are happy with them and GHC accepts as path separator And relative paths don t depend on where cygwin s root directory is located or on which partition or network drive your source tree happens to reside as long as you cd there first If you have to use absolute paths beware of the innocent looking ROOT pwd in makefile hierarchies or configure scripts cygwin provides a tool called cygpath that can convert cygwin s unix style paths to their actual windows style counterparts Many cygwin tools actually accept absolute windows style paths remember though tha
459. nated entirely The following are good producers e List comprehensions e Enumerations of Int Integer and Char e g a z e Explicit lists e g True False e The cons constructor e g 3 4 e map e take filter e iterate repeat zip zipWith The following are good consumers e List comprehensions array on its second argument e on its first argument foldr e map e take filter e concat unzip unzip2 unzip3 unzip4 e zip zipWith but on one argument only if both are good producers zip will fuse with one but not the other partition e head and or any all sequence_ e msum So for example the following should generate no intermediate lists ON A EIA 2 lt ime CF il OD This list could readily be extended if there are Prelude functions that you use a lot which are not included please tell us If you want to write your own good consumers or producers look at the Prelude definitions of the above functions to see how to do so The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 272 327 7 23 6 Specialisation Rewrite rules can be used to get the same effect as a feature present in earlier versions of GHC For example suppose that genericLookup Ord a gt Table a b gt 6 19 intLookup cys LelolS dat 19 gt ine gt 19 where int Lookup is an implementation of genericLookup that works very fast for
460. ncluding expressions which are not fully evaluated Annotation expressions will be evaluated by the compiler just like Template Haskell splices are So this annotation is fine The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 297 327 ANN f SillyAnnotation foo id 10 20 bar 4E f 9 1 2 Annotating types You can annotate types with the ANN pragma by using the t ype keyword For example ANN type Foo Just A Maybe String annotation ATAR OS 9 1 3 Annotating modules You can annotate modules with the ANN pragma by using the module keyword For example ANN module Just A Maybe String annotation 9 2 Using GHC as a Library The ghc package exposes most of GHC s frontend to users and thus allows you to write programs that leverage it This library is actually the same library used by GHC s internal frontend compilation driver and thus allows you to write tools that programmatically compile source code and inspect it Such functionality is useful in order to write things like IDE or refactoring tools As a simple example here s a program which compiles a module much like ghc itself does by default when invoked import GHC import GHC Paths libdir import DynFlags defaultLogAction main defaultErrorHandler defaultLogAction do awane US Eo A S clo dflags lt getSessionDynFlags setSessionDynFlags dflags target lt gue
461. nction which also takes a descriptive string to include in the error message and perhaps combine this with the use of a pre processor which inserts the source location where assert was used Ghc offers a helping hand here doing all of this for you For every use of assert in the user s source kelvinToC Double gt Double kelvinToC k assert k gt 0 0 k 273 15 Ghc will rewrite this to also include the source location where the assertion was made assert pred val gt assertError Main hs 15 pred val The rewrite is only performed by the compiler when it spots applications of Control Exception assert so you can still define and use your own versions of assert should you so wish If not import Control Exception to make use assert in your code GHC ignores assertions when optimisation is turned on with the O flag That is expressions of the form assert pred e will be rewritten to e You can also disable assertions using the fignore asserts option The option fno ignore asserts allows enabling assertions even when optimisation is turned on Assertion failures can be caught see the documentation for the Control Exception library for the details 7 21 Static pointers The language extension XStaticPointers adds a new syntactic form static e which stands for a reference to the closed expression e This reference is stable and portable in the sense that 1t remains valid across different processes on p
462. nd ST monads use unboxed tuples to avoid unnecessary allocation during sequences of operations There are some restrictions on the use of unboxed tuples e Values of unboxed tuple types are subject to the same restrictions as other unboxed types i e they may not be stored in polymorphic data structures or passed to polymorphic functions e The typical use of unboxed tuples is simply to return multiple values binding those multiple results with a case expression thus Wy Gr erly wel a eaae jr x be one f Gi ai ID 47 e a ar ley X X You can have an unboxed tuple in a pattern binding thus ioe ler Er oera 11 se alin 4 Oe If the types of p and q are not unboxed the resulting binding is lazy like any other Haskell pattern binding The above example desugars like this AS IS E 4 gt Cope 3 PA rer ic a Sme ic IA O Indeed the bindings can even be recursive 7 3 Syntactic extensions 7 3 1 Unicode syntax The language extension XUnicodeSyntax enables Unicode characters to be used to stand for certain ASCII character se quences The following alternatives are provided ASCII Unicode alternative The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 155 327 ASCII Unicode alternative gt gt forall y gt gt lt lt x gt gt lt lt gt gt 7 3 2 The magic hash The
463. nd driven basis rather than a depth first basis as in strict languages The stack in GHC s execution engine bears little resemblance to the lexical call stack Ideally GHCi would maintain a separate lexical call stack in addition to the dynamic call stack and in fact this is exactly what our profiling system does Chapter 5 and what some other Haskell debuggers do For the time being however GHCi doesn t maintain a lexical call stack there are some technical The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 29 327 challenges to be overcome Instead we provide a way to backtrack from a breakpoint to previous evaluation steps essentially this is like single stepping backwards and should in many cases provide enough information to answer the how did I get here question To use tracing evaluate an expression with the trace command For example if we set a breakpoint on the base case of qsort Main gt list qsort i gsore H Al LIS CEA SI ES OS AS O 3 where left right filter lt a as filter gt a as 4 Main gt b 1 Breakpoint 1 activated at qsort hs 1 11 12 Main gt and then run a small qsort with tracing Main gt trace qsort 3 2 1 SEOoPpped tartas Oster nis lia res uIE ss el Essorsa Sed ii Mea We can now inspect the history of evaluation steps iasonrtm aist TA Mo ES E ES OE hse 2453 3 4 2 Bone Aayo Ao OI ES OS AOSS 8 S ice jase RL
464. nd should not be used 1 5 3 4 binary Version number 0 7 3 0 was 0 7 1 0 1 5 3 5 bytestring Version number 0 10 6 0 was 0 10 4 0 1 5 3 6 Cabal Version number 1 22 1 0 was 1 18 1 3 1 5 3 7 containers Version number 0 5 6 2 was 0 5 4 0 1 5 3 8 deepseq Version number 1 4 1 1 was 1 3 0 2 1 5 3 9 directory Version number 1 2 2 0 was 1 2 0 2 1 5 3 10 filepath Version number 1 4 0 0 was 1 3 0 2 1 5 3 11 ghc Many internal functions in GHC related to package IDs have been renamed to refer to package keys e g Packageld is now PackageKey the wired in names such as primPackageld are now primPackageKey etc This reflects a distinction that we are now making a package ID is as before the user visible ID from Cabal foo 1 0 a package key is now a compiler internal entity used for generating linking symbols and may not correspond at all to the package ID In particular there may be multiple package keys per package ID The ghc library no longer depends on the Cabal library This means that users of the ghc library are no longer forced to use the same version of Cabal as ghc did It also means that Cabal is freed up to be able to depend on packages that ghc does not want to depend on which for example may enable improvements to Cabal s parsing infrastructure 1 5 3 12 ghc prim Version number 0 4 0 0 was 0 3 1 0 The low level prefetch API exported by GHC Prim added in GHC 7 8 has been overhauled
465. ndexed type families come in three flavours data families open type synonym families and closed type synonym families They are the indexed family variants of algebraic data types and type synonyms respectively The instances of data families can be data types and newtypes Type families are enabled by the flag XTypeFamilies Additional information on the use of type families in GHC is available on the Haskell wiki page on type families 7 7 1 Data families Data families appear in two flavours 1 they can be defined on the toplevel or 2 they can appear inside type classes in which case they are known as associated types The former is the more general variant as it lacks the requirement for the type indexes to coincide with the class parameters However the latter can lead to more clearly structured code and compiler warnings if some type instances were possibly accidentally omitted In the following we always discuss the general toplevel form first and then cover the additional constraints placed on associated types The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 208 327 7 7 1 1 Data family declarations Indexed data families are introduced by a signature such as daran Emel Ne 88 ty The special family distinguishes family from standard data declarations The result kind annotation is optional and as usual defaults to if omitted An example is data family Array e Named ar
466. ng algorithm but the savings in memory use can be considerable For a given heap size using the H option compaction can in fact reduce the GC cost by allowing fewer GCs to be performed This is more likely when the ratio of live data to heap size is high say gt 30 NOTE compaction doesn t currently work when a single generation is requested using the G1 option cn Default 30 Automatically enable compacting collection when the live data exceeds n of the maximum heap size see the M option Note that the maximum heap size is unlimited by default so this option has no effect unless the maximum heap size is set with Msi ze Ffactor Default 2 This option controls the amount of memory reserved for the older generations and in the case of a two space collector the size of the allocation area as a factor of the amount of live data For example if there was 2M of live data in the oldest generation when we last collected it then by default we ll wait until it grows to 4M before collecting it again The default seems to work well here If you have plenty of memory it is usually better to use Hsi ze than to increase F factor The F setting will be automatically reduced by the garbage collector when the maximum heap size the Msi ze setting is approaching Ggenerations Default 2 Set the number of generations used by the garbage collector The default of 2 seems to be good but the garbage collector can suppor
467. ng imported with the safe keyword must be a trusted module otherwise a compilation error will occur The safe import extension is enabled by either of the XSafe XTrustworthy or XUnsafe flags and corresponding PRAGMA s When the XSafe flag is used the safe keyword is allowed but meaningless every import is required to be safe regardless 7 29 4 Trust and Safe Haskell Modes The Safe Haskell extension introduces the following three language flags XSafe Enables the safe language dialect asking GHC to guarantee trust The safe language dialect requires that all imports be trusted or a compilation error will occur XTrustworthy Means that while this module may invoke unsafe functions internally the module s author claims that it exports an API that can t be used in an unsafe way This doesn t enable the safe language or place any restrictions on the allowed Haskell code The trust guarantee is provided by the module author not GHC An import statement with the safe keyword results in a compilation error if the imported module is not trusted An import statement without the keyword behaves as usual and can import any module whether trusted or not XUnsafe Marks the module being compiled as unsafe so that modules compiled using XSafe can t import it The procedure to check if a module is trusted or not depends on if the fpackage trust flag is present The check is very similar in both cases with the presence of the
468. nge their type not when they change their implementation fomit yields On by default Tells GHC to omit heap checks when no allocation is being performed While this improves binary sizes by about 5 it also means that threads run in tight non allocating loops will not get preempted in a timely fashion If it is important to always be able to interrupt such threads you should turn this optimization off Consider also recompiling all libraries with this optimization turned off if you need to guarantee interruptibility fpedantic bottoms Make GHC be more precise about its treatment of bottom but see also fno state hack In particular stop GHC eta expanding through a case expression which is good for performance but bad if you are using seq on partial applications fregs graph Off by default due to a performance regression bug Only applies in combination with the native code generator Use the graph colouring register allocator for register allocation in the native code generator By default GHC uses a simpler faster linear register allocator The downside being that the linear register allocator usually generates worse code fregs iterative Off by default only applies in combination with the native code generator Use the iterative coalescing graph colouring register allocator for register allocation in the native code generator This is the same register allocator as the fregs graph one but also enables iterative coalescing during re
469. ngth the behaviour of fromListN is not specified The function toList should be the inverse of fromList It is perfectly fine to declare new instances of IsList so that list notation becomes useful for completely new data types Here are several example instances instance IsList a where type Item a a fromList id COs ad instance Ord a gt IsList Set a where type Item Set a a fromList Set fromList toList Set toList instance Ord k gt IsList Map k v where type Item Map k v k v fromList Map fromList toList Map toList instance IsList IntMap v where type Item IntMap v Int v fromList IntMap fromList toList IntMap toList instance IsList Text where type Item Text Char fromList Text pack toList Text unpack instance IsList Vector a where type Item Vector a a fromList Vector fromList fromListN Vector fromListN toList Vector toList 7 6 5 2 Rebindable syntax When desugaring list notation with XOverloadedLists GHC uses the fromList etc methods from module GHC Exts You do not need to import GHC Ext s for this to happen However if you use XRebindableSyntax then GHC instead uses whatever is in scope with the names of toList from List and fromListN That is these functions are rebindable c f Section 7 3 16 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 207 327 7 6 5 3 Defaulting
470. nkNTypes XRecursiveDo XScopedTypeVariables XStandaloneDeriving XTypeOperators XTypeSynonym Instances XUnboxedTuples XUnicodeSyntax XUnliftedFFITypes Enabling these options is the only ef fect of Eglasgow exts We are trying to move away from this portmanteau flag and towards enabling features individually 7 2 Unboxed types and primitive operations GHC is built on a raft of primitive data types and operations primitive in the sense that they cannot be defined in Haskell itself While you really can use this stuff to write fast code we generally find it a lot less painful and more satisfying in the long run The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 153 327 to use higher level language features and libraries With any luck the code you write will be optimised to the efficient unboxed version in any case And if it isn t we d like to know about it All these primitive data types and operations are exported by the library GHC Prim for which there is detailed online documen tation This documentation is generated from the file compiler prelude primops txt pp If you want to mention any of the primitive data types or operations in your program you must first import GHC Prim to bring them into scope Many of them have names ending in and to mention such names you need the KMagicHash extension Section 7 3 2 The primops make extensive
471. nonyms The name of the pattern synonym itself is in the same namespace as proper data constructors In an export or import specification you must prefix pattern names with the pattern keyword e g module Example pattern Single where pattern Single x x The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 161 327 Without the pattern prefix Single would be interpreted as a type constructor in the export list You may also use the pattern keyword in an import export specification to import or export an ordinary data constructor For example import Data Maybe pattern Just would bring into scope the data constructor Just from the Maybe type without also bringing the type constructor Maybe into scope 7 3 9 3 Typing of pattern synonyms Given a pattern synonym definition of the form pae cenn I yanl Vear NS AO e it is assigned a pattern type of the form parecia 1 88 Ciao gt Cee gt wil gt 62 gt gag gt iN gt E where CProv and CReg are type contexts and t1 t2 tN and t are types Notice the unusual form of the type with two contexts CProv and CReq e CReq are the constraints required to match the pattern e CProv are the constraints made available provided by a successful pattern match For example consider data T a where MII Be Slavery Io SS 2 e lo S I el Bigg ner NUI gt Wik lt i gt SEELE fl MkT 42 x show x patter
472. nonyms in XTypeSynonymInsta instance heads Implied by dynannie XNoTypeSynonymIns nces tances XFlexiblelnstances XUnboxedTuples Enable unboxed tuples dynamic XNoUnboxedTuples XUndecidablelnsta Enable undecidable dani XNoUndecidablelns nces instances tances XUnicodeSyntax Enable unicode syntax dynamic XNoUnicodeSyntax XUnliftedFFITypes Enable unlifted FFI types dynamic N Enable Safe Haskell Unsafe XUnsafe dynamic mode XViewPatterns Enable view patterns dynamic XNoViewPatterns 4 19 13 Warnings Section 4 8 Flag Description Static Dynamic Reverse W enable normal warnings dynamic w WwW disable all warnings dynamic enable almost all warnings Wall details in Section 4 8 E dynamic Werror make warnings fatal dynamic Wwarn Wwarn make warnings non fatal dynamic Werror Turn type errors into warnings deferring the ES error nel nee Implies dynamic ee errors errors fdefer typed holes Convert typed hole errors into warnings deferring the fdefer typed error until runtime Implied e fno defer typed holes by fdefer typ holes errors See also fwarn typed holes pets Make suggestions for dyntinie fno helpful mis spelled names errors warn about uses of B fwarn deprecated j fno warn fiags commandline flags that are dynamic deprecated flags deprecated 5x warn when a constraint fno warn 7 twarn Aup acs appears duplicated in a type dynamic duplicate constraints signature constraints fwar
473. ns out that such recursive bindings do indeed make sense for a variety of monads but not all In particular recursion in this sense requires a fixed point operator for the underlying monad captured by the mfix method of the MonadFix class defined in Control Monad Fix as follows class Monad m gt MonadFix m where miix e ma gt ma Haskell s Maybe list ST both strict and lazy versions 10O and many other monads have MonadF ix instances On the negative side the continuation monad with the signature a gt r gt r does not For monads that do belong to the MonadF ix class GHC provides an extended version of the do notation that allows recursive bindings The XRecursiveDo language pragma RecursiveDo provides the necessary syntactic support introducing the keywords mdo and rec for higher and lower levels of the notation respectively Unlike bindings in a do expression those introduced by mdo and rec are recursively defined much like in an ordinary let expression Due to the new keyword mdo we also call this notation the mdo notation Here is a simple albeit contrived example LANGUAGE RecursiveDo justOnes mdo xs lt Just 1 xs return map negate xs or equivalently LANGUAGE RecursiveDo justOnes do rec xs lt Just 1 xs return map negate xs As you can guess justOnes will evaluate to Just 1 1 1 GHC s implementation the mdo notation cl
474. nsitivity to hi interface files GHC is very sensitive about interface files For example if it picks up a non standard Pre lude hi file pretty terrible things will happen If you turn on XNoImplicitPrelude the compiler will almost surely die unless you know what you are doing Furthermore as sketched below you may have big problems running programs compiled using unstable interfaces I think GHC is producing incorrect code Unlikely A useful be more paranoid option to give to GHC is dcore lint this causes a lint pass to check for errors notably type errors after each Core to Core transformation pass We run with dcore lint on all the time it costs about 5 in compile time Why did I get a link error If the linker complains about not finding _ lt something gt _fast then something is inconsis tent you probably didn t compile modules in the proper dependency order Ts this line number right On this score GHC usually does pretty well especially if you allow it to be off by one or two In the case of an instance or class declaration the line number may only point you to the declaration not to a specific method Please report line number errors that you find particularly unhelpful 10 2 When your program does the wrong thing For advice about overly slow or memory hungry Haskell programs please see Chapter 6 The Glorious Glasgow Haskell Compilation System User s Guide Vers
475. nstalled the filepath package and this has caused various dependencies including Cabal to break ghc pkg list WARNING there are broken packages Run ghc pkg check for more details US AE ohne or 2e package rcon ed Cabal 1 7 4 diray Orori paser rore Sire Additionally ghc pkg list reminds you that there are broken packages and suggests ghc pkg check which displays more information about the nature of the failure ghc pkg check There are problems in package ghc 6 12 1 dependency filepath 1 1 0 1 87511764eb0af2bce4db05e702750e63 doesn t exist here are problems in package haskeline 0 6 2 dependency filepath 1 1 0 1 87511764eb0af2bce4db05e702750e63 doesn t exist There are problems in package Cabal 1 7 4 dependency filepath 1 1 0 1 87511764eb0af2bce4db05e702750e63 doesn t exist There are problems in package process 1 0 1 1 dependency filepath 1 1 0 1 87511764eb0af2bce4db05e702750e63 doesn t exist here are problems in package directory 1 0 0 2 dependency filepath 1 1 0 1 87511764eb0af2bce4db05e702750e63 doesn t exist he following packages are broken either because they have a problem listed above or because they depend on a broken package ale 12 AL haskeline 0 6 2 Capa E ERA process IO directory 1 0 0 2 bin package db 0 0 0 0 mae 3 0 2 haskel198 1 0 1 0 To fix the problem you need to recompile the broken packages against the new dep
476. nstance Monad m gt Monad State s m instance Monad m gt Monad Failure m In Haskell 98 we can define a parsing monad by type Parser tok m a State tok Failure m a which is automatically a monad thanks to the instance declarations above With the extension we can make the parser type abstract without needing to write an instance of class Monad via The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 191 327 newtype Parser tok m a Parser State tok Failure m a deriving Monad In this case the derived instance declaration is of the form instance Monad State tok Failure m gt Monad Parser tok m Notice that since Monad is a constructor class the instance is a partial application of the new type not the entire left hand side We can imagine that the type declaration is eta converted to generate the context of the instance declaration We can even derive instances of multi parameter classes provided the newtype is the last class parameter In this case a partial application of the class appears in the deriving clause For example given the class class StateMonad s m m gt s where instance Monad m gt StateMonad s State s m where then we can derive an instance of StateMonad for Parsers by newtype Parser tok m a Parser State tok Failure m a deriving Monad StateMonad tok The derived instance is obtained by completing the application of the class t
477. nstance would have to return a member of k for any k However this is not the case The type family UnEx is a kind indexed type family The return kind k is an implicit parameter to UnEx The elaborated definitions are as follows type familly UNE BOS ex Ex sk type instance UnEx k MkEx k x x Thus the instance triggers only when the implicit parameter to UnEx matches the implicit parameter to MkEx Because k is actually a parameter to UnEx the kind is not escaping the existential and the above code is valid See also Trac 7347 7 9 6 Promoting type operators Type operators are not promoted to the kind level Why not Because x is a kind parsed the way identifiers are Thus if a programmer tried to write Either Bool would it be Either applied to x and Bool Or would it be x applied to Either and Bool To avoid this quagmire we simply forbid promoting type operators to the kind level 7 10 Type Level Literals GHC supports numeric and string literals at the type level giving convenient access to a large number of predefined type level constants Numeric literals are of kind Nat while string literals are of kind Symbol This feature is enabled by the XDataKinds language extension The kinds of the literals and all other low level operations for this feature are defined in module GHC TypeLits Note that the module defines some type level operators that clash with their value level counterpart
478. nstr threshold fspecialise Turn on specialisation of overloaded functions Implied by 0 dynamic fno specialise fstatic argument transformation Turn on the static argument transformation dynamic fno static argument transformation fstrictness Turn on strictness analysis Implied by 0 dynamic fno strictness The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 124 327 Flag Description Static Dynamic Reverse Run an additional strictness fstractness i A analysis before simplifier dynamic before n phase n Flatten strict constructor funbox small fields with a pointer sized dynamic fno unbox small strict fields representation Implied by y strict fields 0 funbox strict Flatten strict constructor Annie fno unbox strict fields fields 4 fields funfolding y Tweak unfolding settings creation Default 750 dynamic threshold n funfolding dict Tweak unfolding settings dynamic discount n Default 30 y funfolding fun Tweak unfolding settings dynamig discount n Default 60 y funfolding Tweak unfolding settings dynamic keeness factor n Default 1 5 y funfolding use Tweak unfolding settings dynamit i threshold n Default 60 y Enable vectorisation fno fvectorisation s avoi
479. ntains open layout contexts see Section 2 4 3 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 39 327 r Normally any evaluation of top level expressions otherwise known as CAFs or Constant Applicative Forms in loaded modules is retained between evaluations Turning on r causes all evaluation of top level expressions to be discarded after each evaluation they are still retained during a single evaluation This option may help if the evaluated top level expressions are consuming large amounts of space or if you need repeatable performance measurements s Display some stats after evaluating each expression including the elapsed time and number of bytes allocated NOTE the allocation figure is only accurate to the size of the storage manager s allocation area because it is calculated at every GC Hence you might see values of zero if no GC has occurred t Display the type of each variable bound after a statement is entered at the prompt If the statement is a single expression then the only variable binding will be for the variable it 2 8 2 Setting GHC command line options in GHCi Normal GHC command line options may also be set using set For example to turn on fwarn missing signatures you would say Prelude gt set fwarn missing signatures Any GHC command line option that is designated as dynamic see the table in Section 4 19 may be set using set To unset an option
480. ntel Pentium 4 and later or AMD Athlon 64 and later The LLVM backend will also use SSE2 if your processor supports it but detects this automatically so no flag is required SSE2 is unconditionally used on x86 64 platforms msse4 2 x86 only added in GHC 7 4 1 Use the SSE4 2 instruction set to implement some floating point and bit operations when using the native code generator The resulting compiled code will only run on processors that support SSE4 2 Intel Core i7 and later The LLVM backend will also use SSE4 2 if your processor supports it but detects this automatically so no flag is required The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 96 327 4 17 Running a compiled program To make an executable program the GHC system compiles your code and then links it with a non trivial runtime system RTS which handles storage management thread scheduling profiling and so on The RTS has a lot of options to control its behaviour For example you can change the context switch interval the default size of the heap and enable heap profiling These options can be passed to the runtime system in a variety of different ways the next section Section 4 17 1 describes the various methods and the following sections describe the RTS options themselves 4 17 1 Setting RTS options There are four ways to set RTS options e on the command line between RTS RTS when running the program Section 4
481. nter MS SW same E CES ay O ES weep Wish main do display inc counterA gt daa WI display inc inc counterB prints if Record update syntax is supported for existentials and GADTs SEUA ss COU Milian a gt COMM cites setTag obj t obj tag t The rule for record update is this the types of the updated fields may mention only the universally quantified type variables of the data constructor For GADTs the field may mention only types that appear as a simple type variable argument in the constructor s result type For example Sata Wao Wheres Ast ie ea be ea ord tate a eL c is existential UPA Sie facile Oh tpc eo We lj e ey gt E a Io Ufo AZ E A ESS BAD 3 s type mentions c which is The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 182 327 existentially quantified datwavG taba wherewsGilen ga Zi Cun Ce wael ep 3 ep E OKs tics 35 al S RO upd4 g x g g2 x BAD f2 s type mentions Cc which is not a simple type variable argument in Gl s result type 7 4 6 4 Restrictions There are several restrictions on the ways in which existentially quantified constructors can be use e When pattern matching each pattern match introduces a new distinct type for each existential type variable These types cannot be unified with any other type nor can they escape from the scope of the pattern match For example these f
482. num while 11 do sleep 10 neac ESSE N DAS AMBER E IN ewe SA DON hp2ps gt FOO ps kill HUP Sgvpsnum done 5 6 Profiling Parallel and Concurrent Programs Combining threaded and prof is perfectly fine and indeed it is possible to profile a program running on multiple proces sors with the RTS N option 3This feature was added in GHC 7 4 1 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 143 327 Some caveats apply however In the current implementation a profiled program is likely to scale much less well than the unprofiled program because the profiling implementation uses some shared data structures which require locking in the runtime system Furthermore the memory allocation statistics collected by the profiled program are stored in shared memory but not locked for speed which means that these figures might be inaccurate for parallel programs We strongly recommend that you use fno prof count entries when compiling a program to be profiled on multiple cores because the entry counts are also stored in shared memory and continuously updating them on multiple cores is extremely slow We also recommend using ThreadScope for profiling parallel programs it offers a GUI for visualising parallel execution and is complementary to the time and space profiling features provided with GHC 5 7 Observing Code Coverage Code coverage tools allow a programmer to dete
483. nv varl m2 lookup env var2 okl maybeToBool ml ok2 maybeToBool m2 vall expectJust ml val2 expectJust m2 The auxiliary functions are maybeToBool Maybe a gt Bool maybeToBool Just x True maybeToBool Nothing False expectJust Maybe a gt a expectJust Just x x expectJust Nothing error Unexpected Nothing What is clunky doing The guard ok1 amp amp ok2 checks that both lookups succeed using maybeToBool to convert the Maybe types to booleans The lazily evaluated expectJust calls extract the values from the results of the lookups and binds the returned values to val1 and val2 respectively If either lookup fails then clunky takes the otherwise case and returns the sum of its arguments This is certainly legal Haskell but it is a tremendously verbose and un obvious way to achieve the desired effect Arguably a more direct way to write clunky would be to use case expressions The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 157 327 clunky env varl var2 case lookup env varl of Nothing gt fail Just vall gt case lookup env var2 of Nothing gt fail Jest veda gt yall valz where fail varl var2 This is a bit shorter but hardly better Of course we can rewrite any set of pattern matching guarded equations as case expres sions that is precisely what the compiler does when compiling equations The reason that Haskell provides guarded equation
484. ny discounts that apply depending on the context into which the expression is to be inlined The difference between this and funfolding creation threshold is that this one determines if a function definition will be inlined at a call site The other option determines if a function definition will be kept around at all for potential inlining fvectorisation avoidance Part of Data Parallel Haskell DPH On by default Enable the vectorisation avoidance optimisation This optimisation only works when used in combination with the fvectorise transformation While vectorisation of code using DPH is often a big win it can also produce worse results for some kinds of code This optimisation modifies the vectorisation transformation to try to determine if a function would be better of unvectorised and if so do just that fvectorise Part of Data Parallel Haskell DPH Off by default Enable the vectorisation optimisation transformation This optimisation transforms the nested data paral lelism code of programs using DPH into flat data parallelism Flat data parallel programs should have better load balancing enable SIMD parallelism and friendlier cache behaviour The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 84 327 4 11 GHC Backends GHC supports multiple backend code generators This is the part of the compiler responsible for taking the last intermediate representation that GHC uses a form called
485. ny foreign exported functions 8 2 4 4 On the use of hs_exit hs_exit normally causes the termination of any running Haskell threads in the system and when hs_exit returns there will be no more Haskell threads running The runtime will then shut down the system in an orderly way generating profiling output and statistics if necessary and freeing all the memory it owns It isn t always possible to terminate a Haskell thread forcibly for example the thread might be currently executing a foreign call and we have no way to force the foreign call to complete What s more the runtime must assume that in the worst case the Haskell code and runtime are about to be removed from memory e g if this is a Windows DLL hs_exit is normally called before unloading the DLL So hs_exit must wait until all outstanding foreign calls return before it can return itself The upshot of this is that if you have Haskell threads that are blocked in foreign calls then hs_exit may hang or possibly busy wait until the calls return Therefore it s a good idea to make sure you don t have any such threads in the system when The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 295 327 calling hs_exit This includes any threads doing I O because I O may or may not depending on the type of I O and the platform be implemented using blocking foreign calls The GHC runtime treats program exit as a special case
486. o output t produces a single line of output in the same format as GHC s Rghc timing option s produces a more detailed summary at the end of the program and S additionally produces information about each and every garbage collection The output is placed in file If file is omitted then the output is sent to stderr If you use the T flag then you should access the statistics using GHC Stats If you use the t flag then when your program finishes you will see something like this lt lt ghc 36169392 bytes 69 GCs 603392 1065272 avg max bytes residency 2 samples 3M in use 0 00 INIT 0 00 elapsed 0 02 MUT 0 02 elapsed 0 07 GC 0 07 elapsed ghc gt gt This tells you e The total number of bytes allocated by the program over the whole run e The total number of garbage collections performed e The average and maximum residency which is the amount of live data in bytes The runtime can only determine the amount of live data during a major GC which is why the number of samples corresponds to the number of major GCs and is usually relatively small To get a better picture of the heap profile of your program use the hT RTS option Section 4 17 5 e The peak memory the RTS has allocated from the OS e The amount of CPU time and elapsed wall clock time while initialising the runtime system INIT running the program itself MUT the mutator and garbage collecting GC You can also get this in a m
487. o call from the outside For example Adder hs LANGUAGE ForeignFunctionInterface module Adder where ceileir 83 ime gt dime gt 10 Lime GEELEVLICONS WSS oF LO adder x y return x y 1E IgSulein Eyer sicoleelil eyeleisie He A O AE Add some helper code that starts up and shuts down the Haskell RTS StartEnd c include lt Rts h gt vola Es stan sLigie GuEcie Ife charx argv ghcD11 NULL argv must end with NULL Initialize Haskell runtime char args argv hs_init amp argc amp args void HsEnd hs_exit Here Adder is the name of the root module in the module tree as mentioned above there must be a single root module and hence a single module tree in the DLL Compile everything up ghe c Adder hs cine e Sitensciamal e ghel shared o Adder dll Adder o Adder_stub o StartEnd o Now the file Adder d11 can be used from other programming languages Before calling any functions in Adder it is necessary to call HsStart and at the very end call HsEnd Warning It may appear tempting to use D1 1Main to call hs_init hs_exit but this won t work particularly if you compile with threaded There are severe restrictions on which actions can be performed during D11Main and hs_init violates these restrictions which can lead to your dll freezing during startup see bug 3605 12 6 2 1 Using from VBA An example of using Adder d11 from VBA is
488. o declare an ordinary algebraic data type using GADT style syntax What makes a GADT into a GADT is not the syntax but rather the presence of data constructors whose result type is not just T a b You cannot use a deriving clause for a GADT only for an ordinary data type As mentioned in Section 7 4 7 record syntax is supported For example data Term a where iat os wel 23 me gt Term Int suce Rag sum Term int gt Term nt Pred da som lt lt Term Int p Term nt IsZero arg t Term Int gt Term Bool Pair sas argl Terma p Gus Be Wien 19 gt Term a b 1155 cia end Term Bool p CLU s Term a p ELS 2 Term a gt Term a However for GADTs there is the following additional constraint every constructor that has a field must have the same result type modulo alpha conversion Hence in the above example we cannot merge the num and arg fields above into a single name Although their field types are both Term Int their selector functions actually have different types nom 15 Lem lat gt term nt ewe ss Term BOOL gt Temim amie When pattern matching against data constructors drawn from a GADT for example in a case expression the following rules apply The type of the scrutinee must be rigid The type of the entire case expression must be rigid The type of any free variable mentioned in any of the case alternatives must be rigid A type is rigid if it is completely kno
489. o get started With that in mind this introductory section provides a quick introduction to the basic usage of GHC for compiling a Haskell program before the following sections dive into the full syntax Let s create a Hello World program and compile and run it First create a file hello hs containing the Haskell code main putStrLn Hello World To compile the program use GHC like this ghc hello hs where represents the prompt don t type it GHC will compile the source file hello hs producing an object file hello o and an interface file hello hi and then it will link the object file to the libraries that come with GHC to produce an executable called hello on Unix Linux Mac or hello exe on Windows By default GHC will be very quiet about what it is doing only printing error messages If you want to see in more detail what s going on behind the scenes add v to the command line Then we can run the program like this Se cito Hello World If your program contains multiple modules then you only need to tell GHC the name of the source file containing the Main module and GHC will examine the import declarations to find the other modules that make up the program and find their source files This means that with the exception of the Main module every source file should be named after the module name that it contains with dots replaced by directory separators For example the module Data Person would be in the fil
490. o separate packages include dirs string list A list of directories containing C includes for this package includes string list A list of files to include for via C compilations using this package Typically the include file s 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 depends package id list Packages on which this package depends hugs options string list Options to pass to Hugs for this package cc options string list Extra arguments to be added to the gcc command line when this package is being used only for via C compilations 1ld options string list Extra arguments to be added to the gec command line for linking when this package is being used framework dirs string list On Darwin MacOS X a list of directories containing frameworks for this package This corresponds to the framework path option It is ignored on all other platforms frameworks string list On Darwin MacOS X a list of frameworks to link to This corresponds to the framework option Take a look at Apple s developer documentation to find out what frameworks actually are This entry is ignored on all other platforms haddock interfaces string list A list of filenames containing Haddock interface files haddock files for this pack age haddock html optional string The directory containing the Haddock generated HTM
491. o the new type instance StateMonad tok State tok Failure m gt StateMonad tok Parser tok m As a result of this extension all derived instances in newtype declarations are treated uniformly and implemented just by reusing the dictionary for the representation type except Show and Read which really behave differently for the newtype and its representation 7 5 5 2 A more precise specification A derived instance is derived only for declarations of these forms after expansion of any type synonyms newtype T vl vn MI verl levita C iil T neWEy pens ano iiS AS AA MI E E V Era V NCE ER E where e v1 vn are type variables and t s1 sk t1 tj are types e The C t1 tj isa partial applications of the class C where the arity of C is exactly j 1 That is C lacks exactly one type argument e k is chosen so that C t1 tj T vl vk is well kinded Or in the case ofa data instance sothatC t1 tj T sl sk is well kinded e The type t is an arbitrary type e The type variables vk 1 wvn do not occur in the types t s1 sk ortl tj e Cis not Read Show Typeable or Data These classes should not look through the type or its constructor You can still derive these classes for a newtype but it happens in the usual way not via this new mechanism e It is safe to coerce each of the methods of C That is the missing last argument to C is not used at a nominal role in any of the C s methods See
492. ode so debugging a package requires finding its source and loading that directly The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 25 327 The command break 2 sets a breakpoint on line 2 of the most recently loaded module in this case qsort hs Specifically it picks the leftmost complete subexpression on that line on which to set the breakpoint which in this case is the expression qsort left a qsort right Now we run the program Main gt main Stopped at gsort hs 2 15 46 resulte 25 lle a iia MS Fa O E qgsort hs 2 15 46 Main gt Execution has stopped at the breakpoint The prompt has changed to indicate that we are currently stopped at a breakpoint and the location qsort hs 2 15 46 To further clarify the location we can use the 1ist command asort sus 2 io 10 AMS inst iL csore 11 I ETS OEA aras SOS A GSC ies 3 where left right filter lt a as filter gt a as The 1ist command lists the source code around the current breakpoint If your output device supports it then GHCi will highlight the active subexpression in bold GHCi has provided bindings for the free variables of the expression on which the breakpoint was placed a left right and additionally a binding for the result of the expression _result These variables are just like other variables that you might define in GHCi you can use them in expressions that you type at the pr
493. of the types fromInteger Integer gt Integer fromInteger forall a Foo a gt Integer gt a fromInteger Num a gt a gt Integer fromInteger Integer gt Bool gt Bool Be warned this is an experimental facility with fewer checks than usual Use dcore lint to typecheck the desugared program If Core Lint is happy you should be all right 7 3 17 Postfix operators The XPostfixOperators flag enables a small extension to the syntax of left operator sections which allows you to define postfix operators The extension is this the left section ems The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 170 327 1s equivalent from the point of view of both type checking and execution to the expression CCN Te for any expression e and operator The strict Haskell 98 interpretation is that the section is equivalent to Ow 1 e y That is the operator must be a function of two arguments GHC allows it to take only one argument and that in turn allows you to write the function postfix The extension does not extend to the left hand side of function definitions you must define such a function in prefix form 7 3 18 Tuple sections The XTupleSections flag enables Python style partially applied tuple constructors For example the following program True is considered to be an alternative notation for the more unwieldy alternative Nx gt x True
494. ok SR rra a A ee 176 Extensions to data types and type synonyms 2 2 ee ee 177 7 4 1 Datatypes with no constructors ee 177 714 2 Data type contexts seos bk kee eR ee eae DR A ee Ee we 177 7 4 3 Infix type constructors classes and type variables 0 0 00 00000000004 177 TAA Typeoperators est die on Be E e AS A RS od 178 7 4 5 Liberalised type synonyms 2 ee 178 7 4 6 Existentially quantified data constructors sooo ee 180 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 xi TAGOT Why existential o e sarsa qoon e raid a E e a 180 7 4 6 2 Existentials and type Classes e 180 TA63 Record Constructors s ssec sess ssoco nsss eeror serar aante 181 TAGA Restrictions es ossa ratene e a A e ae ee 182 7 4 7 Declaring data types with explicit constructor signatures o ooo ee ee 183 7 4 8 Generalised Algebraic Data Types GADTs oaaae 186 7 5 Extensions to the deriving mechanism 187 7 5 1 Inferred context for deriving clauses ee 187 7 5 2 Stand alone deriving declarations 20 2 ee 188 7 5 3 Deriving instances of extra classes Data etc o oo ee 189 7 5 4 Deriving Typeable Instantes 189 7 5 5 Generalised derived instances fornewtypes 2 ee 190 7 5 5 1 Generalising the deriving clause ee 190 7 5 5 2 Amore precise specification 2 ee 191 7 5 6 Deriving any other clas
495. ome reason Mingw ships with the readline library but not with the readline headers As a result GHC like Hugs does not use readline for interactive input on Windows You can get a close simulation by using an emacs shell buffer 12 4 Differences in library behaviour Some of the standard Haskell libraries behave slightly differently on Windows On Windows the Z character is interpreted as an end of file character so if you read a file containing this character the file will appear to end just before it To avoid this use IOExts openFileEx to open a file in binary untranslated mode or change an already opened file handle into binary mode using IOExts hSetBinaryMode The IOExts module is part of the Lang package 12 5 Using GHC and other GHC compiled executables with cygwin 12 5 1 Background The cygwin tools aim to provide a unix style API on top of the windows libraries to facilitate ports of unix software to windows To this end they introduce a unix style directory hierarchy under some root directory typically is C cygwin Moreover everything built against the cygwin API including the cygwin tools and programs compiled with cygwin s ghc will see as the root of their file system happily pretending to work in a typical unix environment and finding things like bin and usr include without ever explicitly bothering with their actual location on the windows system probably C cygwin bin and C cygwi
496. ompiled code as well as supporting all the language extensions that GHC provides GHCi also includes an interactive debugger see Section 2 5 2 1 Introduction to GHCi Let s start with an example GHCi session You can fire up GHCi with the command ghci ghei GHCi version 6 12 1 http www haskell org ghc for help Loading package ghc prim linking done Loading package integer gmp linking done Loading package base linking done hoading package Erro done Prelude gt There may be a short pause while GHCi loads the prelude and standard libraries after which the prompt is shown As the banner says you can type to see the list of commands available and a half line description of each of them We ll explain most of these commands as we go along and there is complete documentation for all the commands in Section 2 7 Haskell expressions can be typed at the prompt Prelude gt 1 2 3 Prelude gt let x 42 in x 9 4 666666666666667 Prelude gt GHCi interprets the whole line as an expression to evaluate The expression may not span several lines as soon as you press enter GHCi will attempt to evaluate it In Haskell a let expression is followed by in However in GHCi since the expression can also be interpreted in the IO monad a let binding with no accompanying in statement can be signalled by an empty line as in the above example 2 2 Loading source files Suppose we have
497. ompiler pipeline By default there is the empty plugin which does nothing GhcPlugins defaultPlugin which you should override with record syntax to specify your installation function Since the exact fields of the Plugin type are open to change this is the best way to ensure your plugins will continue to work in the future with minimal interface impact Plugin exports a field installCoreToDos which is a function of type CommandLineOption gt CoreToDo gt CoreM CoreToDo A CommandLineOption is effectively just String and a CoreToDo is basically a function of type Cor gt Core A CoreToDo gives your pass a name and runs it over every compiled module when you invoke GHC As a quick example here is a simple plugin that just does nothing and just returns the original compilation pipeline unmodified and says Hello module DoNothing Plugin plugin where import GhcPlugins pilugam 3g Pluck plugin defaultPlugin installCoreToDos install The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 299 327 install CommandLineOption gt Core tobol gt CoreM CoreToDo install _ todo do reinitializeGlobals PUEMSG Ss Meso I return todo Provided you compiled this plugin and registered it in a package with cabal for instance you can then use it by just specifying fplugin DoNothing Plugin on the command line and during the compilation you should see GHC say Hello N
498. omplete prints the n to m completion candidates for the partial input string 1iteral for the completion domain denoted by type Currently only the rep1 domain is supported which denotes the kind of completion that would be provided interactively by GHCi at the input prompt If omitted n and m default to the first or last available completion candidate respectively If there are less candidates than requested via the range argument n and m are implicitly capped to the number of available completition candidates The output of complete begins with a header line containing three space delimited fields e An integer denoting the number 1 of printed completions e an integer denoting the total number of completions available and finally e a string literal denoting a common prefix to be added to the returned completion candidates The header line is followed by 1 lines each containing one completion candidate encoded as quoted string literal Here are some example invocations showing the various cases Prelude gt complete repl 0 ORO Prelude gt complete repl 5 import For S Zk WOOTE Y Foreign BOBS Cr Foreign C Exrror EOS MC np Foreign C Types Prelude gt complete repl 5 10 import For G Aik suo Y Foreign C Types Foreign Concurrent Foreign ForeignPtr Foreign ForeignPtr Safe Foreign ForeignPtr Unsafe Foreign Marshal Prelude gt complete repl 20 import For EN Foreign StablePtr Foreign
499. ompt you can ask for their types with type and so on There is one important difference though these variables may only have partial types For example if we try to display the value of left qsort hs 2 15 46 Main gt left lt interactive gt 1 0 Ambiguous type variable a in the constraint Show a arising from a use of print at lt interactive gt 1 0 3 Cannot resolve unknown runtime types a Use print or force to determine these types This is because qsort is a polymorphic function and because GHCi does not carry type information at runtime it cannot determine the runtime types of free variables that involve type variables Hence when you ask to display left at the prompt GHCi can t figure out which instance of Show to use so it emits the type error above Fortunately the debugger includes a generic printing command print which can inspect the actual runtime value of a variable and attempt to reconstruct its type If we try it on left qsort hs 2 15 46 Main gt set fprint evld with show sort hisi215 4 6 Maan gt sprint Vert lere tiles ell This isn t particularly enlightening What happened is that left is bound to an unevaluated computation a suspension or thunk and print does not force any evaluation The idea is that print can be used to inspect values at a breakpoint without any unfortunate side effects It won t force any evaluation which could cause the
500. on Unix on Windows then the last database is considered to be the global database and will be modified by default by ghc pkg The intention here is that GHC_PACKAGE_ PATH can be used to create a virtual package environment into which Cabal packages can be installed without setting anything other than GHC_PACKAGE_PATH The ghc pkg program may be run in the ways listed below Where a package name is required the package can be named in full including the version number e g network 1 0 or without the version number Naming a package without the version number matches all versions of the package the specified action will be applied to all the matching packages A package specifier that matches all version of the package can also be written pkg to make it clearer that multiple packages are being matched To match against the installed package ID instead of just package name and version pass the ipid flag ghc pkg init path Creates a new empty package database at path which must not already exist ghc pkg register file Reads a package specification from file which may be to indicate standard input and adds it to the database of installed packages The syntax of file is given in Section 4 9 9 The package specification must be a package that isn t already installed ghc pkg update file Thesame as register except that if a package of the same name is already installed it is replaced by the new one ghc pkg unregi
501. on multiple processors with the goal of improving performance Ideally this should be done invisibly and with no semantic changes e Concurrency means implementing a program by using multiple I O performing threads While a concurrent Haskell program can run on a parallel machine the primary goal of using concurrency is not to gain performance but rather because that is the simplest and most direct way to write the program Since the threads perform I O the semantics of the program is necessarily non deterministic GHC supports both concurrency and parallelism 7 28 1 Concurrent Haskell Concurrent Haskell is the name given to GHC s concurrency extension It is enabled by default so no special flags are required The Concurrent Haskell paper is still an excellent resource as is Tackling the awkward squad To the programmer Concurrent Haskell introduces no new language constructs rather it appears simply as a library Con trol Concurrent The functions exported by this library include e Forking and killing threads e Sleeping e Synchronised mutable variables called MVars e Support for bound threads see the paper Extending the FFI with concurrency 7 28 2 Software Transactional Memory GHC now supports a new way to coordinate the activities of Concurrent Haskell threads called Software Transactional Memory STM The STM papers are an excellent introduction to what STM is and how to use it The main library you need to us
502. only IO to ensue will be to files whose paths were approved by the pathOK test 7 29 2 Safe Language The Safe Haskell safe language guarantees the following properties Referential transparency Functions in the safe language are deterministic evaluating them will not cause any side effects Functions in the IO monad are still allowed and behave as usual Any pure function though as according to its type is guaranteed to indeed be pure This property allows a user of the safe language to trust the types This means for example that the unsafePerformIO I0 a gt a function is disallowed in the safe language Module boundary control Haskell code compiled using the safe language is guaranteed to only access symbols that are publicly available to it through other modules export lists An important part of this is that safe compiled code is not able to examine or create data values using data constructors that it cannot import If a module M establishes some invariants through careful use of its export list then code compiled using the safe language that imports M is guaranteed to respect those invariants Because of this Template Haskell is disabled in the safe language as it can be used to violate this property Semantic consistency The safe language is strictly a subset of Haskell as implemented by GHC Any expression that compiles in the safe language has the same meaning as it does when compiled in normal Haskell In addition in an
503. onoLocalBinds 8 be P y dynamic XNoMonoLocalBinds XTypeFamilies and XGADTs XNoMonomorphismRe Disable the monomorphism moral XMonomorphismRest striction restriction y riction Enable multi parameter XMultiParamTypeCl type classes Implied by ani XNoMultiParamType asses XFunctionalDepende y Classes ncies Enable multi wa 3 XMultiWayIf y dynamic XNoMultiWaylf if expressions XNamedFieldPuns Enable record puns dynamic XNoNamedFieldPuns XNamedWildCards Enable named wildcards dynamic XNoNamedWildCards Enable support for negative 3 XNoNegativeLiter XNegativeLiterals dynamic literals als Disable support for n k XNoNPlusKPatterns dynamic XNPlusKPatterns patterns Deprecated does nothing nullary no parameter type XNull T cl 2 XNoNullaryTypeCla e classes are now enabled dynamic ti Y YP ses sses using XMultiParamTy peClasses Enable support for i XNumDecimals a a dynamic XNoNumDecimals fractional integer literals XOverlappingInsta Enable overlapping dynamic XNoOverlappingIns nces instances y tances X loadedList Enable overloaded lists dynamic F A y XNoOverloadedLists Enable overloaded string XNoOverloadedStri l dynamic XOverloadedStrings literals ngs Enable package qualified XPackagelmports dynamic XNoPackagelmports imports Enable parallel arrays XParallelArrays Implies dynamic XNoParallelArrays XParallelListComp The Glorious Glas
504. ons for each assertion in the context a No type variable has more occurrences in the assertion than in the head b The assertion has fewer constructors and variables taken together and counting repetitions than the head 2 The Coverage Condition For each functional dependency tvsjeft gt tvstignt Of the class every type variable in S tvsrignt must appear in S tvsief where S is the substitution mapping each type variable in the class declaration to the corresponding type in the instance declaration These restrictions ensure that context reduction terminates each reduction step makes the problem smaller by at least one constructor Both the Paterson Conditions and the Coverage Condition are lifted if you give the KUndecidableInstances flag Section 7 6 3 4 You can find lots of background material about the reason for these restrictions in the paper Understanding functional dependencies via Constraint Handling Rules For example these are OK instance C Int a Multiple parameters instance Eq S a Structured type in head Repeated type variable in head instance C4 a a gt C4 a a instance Stateful ST s MutVar s Head can consist of type variables only instance Ca instance Eq a Show b gt C2 ab Non type variables in context instance Show s a gt Show Sized s a instance C2 Int a gt C3 Bool a instance 2 Int a gt 3 al b But these are not Context assert
505. oo To invoke foo from C just include Foo_s tub h andcall foo The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 291 327 The foo_stub cand foo_stub h files can be redirected using the stubdi r option see Section 4 7 4 When linking the program remember to include M_stub o in the final link command line or you ll get link errors for the missing function s this isn t necessary when building your program with ghc make as GHC will automatically link in the correct bits 8 2 1 1 Using your own main Normally GHC s runtime system provides a main which arranges to invoke Main main in the Haskell program However you might want to link some Haskell code into a program which has a main function written in another language say C In order to do this you have to initialize the Haskell runtime system explicitly Let s take the example from above and invoke it from a standalone C program Here s the C code include lt stdio h gt include HsFFI h ifdef _ GLASGOW_HASKELL include foo stub h endif aiae mea ote aoe Caena ela Lie L hs_init 8argc amp argv Fo 1 Os Ll lt 57 deis 4 princi EN ES 2500 Ye hs_exit OF return 0 We ve surrounded the GHC specific bits with ifdef __GLASGOW_HASKELL__ the rest of the code should be portable across Haskell implementations that support the FFI standard The call to hs_init initializes
506. oo polymorphic type like forall a a when used multiple times for types that can not be unified 7 15 Partial Type Signatures nono A partial type signature is a type signature containing special placeholders written with a leading underscore e g _ _ foo _bar called wildcards Partial type signatures are to type signatures what Section 7 14 are to expressions During compila tion these wildcards or holes will generate an error message that describes which type was inferred at the hole s location and information about the origin of any free type variables GHC reports such error messages by default Unlike Section 7 14 which make the program incomplete and will generate errors when they are evaluated this needn t be the case for holes in type signatures The type checker is capable in most cases of type checking a binding with or without a type signature A partial type signature bridges the gap between the two extremes the programmer can choose which parts of a type to annotate and which to leave over to the type checker to infer The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 240 327 By default the type checker will report an error message for each hole in a partial type signature informing the programmer of the inferred type When the XPartialTypeSignatures flag is enabled the type checker will accept the inferred type for each hole generating warnings instead of errors Addi
507. oore oO 28 ime gt MALO Tae ORSINI gt AO The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 289 327 8 1 3 Primitive imports GHC extends the FFI with an additional calling convention prim e g foreign import prim foo foo ByteArray gt Int Int This is used to import functions written in Cmm code that follow an internal GHC calling convention This feature is not intended for use outside of the core libraries that come with GHC For more details see the GHC developer wiki 8 1 4 Interruptible foreign calls This concerns the interaction of foreign calls with Control Concurrent throwTo Normally when the target of a thr owTo is involved in a foreign call the exception is not raised until the call returns and in the meantime the caller is blocked This can result in unresponsiveness which is particularly undesirable in the case of user interrupt e g Control C The default behaviour when a Control C signal is received SIGINT on Unix is to raise the UserInterrupt exception in the main thread if the main thread is blocked in a foreign call at the time then the program will not respond to the user interrupt The problem is that it is not possible in general to interrupt a foreign call safely However GHC does provide a way to inter rupt blocking system calls which works for most system calls on both Unix and Windows When the InterruptibleFFI extension is enabled a foreign call can b
508. options cen display information about sde g the compiler version V display GHC version mode display GHC version numeric version mode numeric only displ HC librar print libdir PEAY C abrar mode directory 4 19 3 Which phases to run Section 4 5 3 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 110 327 Flag Description Static Dynamic Reverse Stop after preprocessing E keopiis mode Stop after generating C C he file mode Stop after generating 2 assembly s file mode j p Stop after generating object od g o file i Override default behaviour i x suffix dynamic for source files 4 19 4 Redirecting output Section 4 7 4 Flag Description Static Dynamic Reverse h ee set the suffix to use for ie iaa intermediate C files y A set directory for interface diia g files l set the suffix to use for hisuf suffix dynamic interface files o filename set output filename dynamic odir dir set directory for object files dynamic a set the filename in which to ohi filename dynamic put the interface osuf suffix set the output file suffix dynamic stubdir dir redirect FFI stub files dynamic dumpdir dir redirect dump files dynamic outputdir dir set output directory dynamic 4 19 5 Kee
509. or to suitable values just as usual For example cul ean EAE al TL Jr a 3 a2 a3 Swizzle a2 MkSwizzle sort a3 MkSwizzle reverse ad MonadT Maybe a4 let r x Just x bm k case m of Just y gt k y Nothing gt Nothing in MkMonad r b mts Woralll as lo gt 9 gt 10 gt A gt e a MAS A s e acy The type of the argument can as usual be more general than the type required as MkSwizzle reverse shows reverse does not need the Ord constraint When you use pattern matching the bound variables may now have polymorphic types For example fo ea E e a SS e Ena A ES ye CI oy 88 Orel ay Orc 19 gt Saal el e a gt 19 ol g MkSwizzle s xs f s map f s xs MonadT m m a gt m a return m x xs bind m x S Xy gt aora sm Uan ime Sesh SINS return m y ys h hm hm In the function h we use the record selectors ret urn and bind to extract the polymorphic bind and return functions from the MonadT data structure rather than using pattern matching The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 233 327 7 13 6 2 Type inference In general type inference for arbitrary rank types is undecidable GHC uses an algorithm proposed by Odersky and Laufer Putting type annotations to work POPL 96 to get a decidable algorithm by requiring some help from the programmer We do not yet have a formal specification of som
510. orall a a by Haskell s usual implicit quantification rules e The signature gives a type for a function binding or a bare variable binding not a pattern binding For example UE A lel gt a E E IS T e E TOK za sa roralil as lal gt Ta ra Ni gt 538 e a 28 8 OK zS O AI lel gt fa gust aes Just Geeses e e e if oe ae a 1 Not OK The binding for 3 is a pattern binding and so its type signature does not bring a into scope However 1 is a function binding and 2 binds a bare variable in both cases the type signature brings a into scope 7 13 8 3 Expression type signatures An expression type signature that has explicit quantification using forall brings into scope the explicitly quantified type variables in the annotated expression For example SN loa gt gt iz 98 SIRE S Int gt G E O PIS PE ST amp Bool Here the type signature forall s ST s Bool brings the type variable s into scope in the annotated expression op gt gt x STRef s Int gt g x The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 236 327 7 13 8 4 Pattern type signatures A type signature may occur in any pattern this is a pattern type signature For example f and g assume that a is already in scope E WG Rae Wesel SS ox g X a x In EI ES ar ay 72 In the case where all the type variables in the pattern type signature ar
511. orall f g xs map f map g xs map f g xs ih The 2 means that the rule is active in Phase 2 and subsequent phases The inverse notation 2 is also accepted meaning that the rule is active up to but not including Phase 2 Rules support the special phase control notation which means the rule is never active This feature supports plugins see Section 9 3 by making it possible to define a RULE that is never run by GHC but is nevertheless parsed typechecked etc so that it is available to the plugin Each variable mentioned in a rule must either be in scope e g map or bound by the forall e g f g xs The variables bound by the foral1 are called the pattern variables They are separated by spaces just like in a type forall A pattern variable may optionally have a type signature If the type of the pattern variable is polymorphic it must have a type signature For example here is the foldr build rule The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 269 327 WieellelWiomatlhel Zorall k z ess toria Ip a Si S19 bo 0 ollo ls 2 owe 0 ke 2 Since g has a polymorphic type it must have a type signature The left hand side of a rule must consist of a top level variable applied to arbitrary expressions For example this is not OK wrongl forall el e2 case True of True gt el False gt e2 el BONA EOL ELL E f True True In wrong1 the LHS i
512. ore future proof machine readable format with t machine readable bytes allocated 36169392 Fini Ges Wes average_bytes_used 603392 max_bytes_used 1065272 num_byte_usage_samples 2 peak_megabytes_allocated 3 Vimeo secon WG OQ Venuinteanwicll ESCO nel Sym O OO muta to Bae pues ec ona si O 02400 mutator_wall_seconds 0 02 ME EMS US SS Om cs A OA OA GC_wall_seconds 0 07 T The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 101 327 If you use the s flag then when your program finishes you will see something like this the exact details will vary depending on what sort of RTS you have e g you will only see profiling data if your RTS is compiled for profiling 36 169 392 bytes allocated in the heap 4 057 632 bytes copied during GC 1 065 272 bytes maximum residency 2 sample s 54 312 bytes maximum slop 3 MB total memory in use 0 MB lost due to fragmentation Generation 0 67 collections 0 parallel O 04s 0 03s elapsed Generation 1 2 collections 0 parallel DOS 0 04s elapsed SPARKS 359207 557 converted 149591 pruned INIT time 0 00s 0 00s elapsed UT time 0 01s 0 02s elapsed GC time 0 07s 0 07s elapsed EXI time 0 00s 0 00s elapsed Total time 0 08s 0 09s elapsed SGC time 89 5 75 3 elapsed Alloc rate 4 520 608 923 bytes per MUT second Productiv
513. oreign exports and multi threading e 294 8 2 4 4 Ontheuseofhs_exit 2 ee 294 8 2 5 Floating point and the FFI ee 295 9 Extending and using GHC as a Library 296 9 1 Sourcesannotations 22826 5 b4 2058 4 ee beet ee bebe estab ee ee Per eb eevdecs 296 9 1 1 Annotating valles 2 2 5 8 4455446 eee EE EA ee e eee awe 296 O12 Annotating types os pendos ee ee poke Ee oR ea oe Ge PA wee we A ae E 297 9 1 3 Annotatng modules sos e gs ep tk kuap e a a ee PA e a Le Ke bee 297 9 2 Usmo GHC as a Library osor pue io e a a EAE AO aD A Des ek Ae ee he ee 297 9 3 Compiler RUSOS ie errada DARAS AA AAN ed 298 93 1 Using compiler plupins ss e tar a a a Eyed BE T amp A 298 9 3 2 Writing compiler plugins sss 6 42 c erene rinses ee ee e E ke 298 9 3 3 Core plugins in more detal es tasai e EER ee 299 9 3 3 1 Manipulating bindings oaaae 299 9 3 3 2 Using Annotations sss e sss cerar a ss t iaso ee 300 93 4 Typechecker plugins gorane de e E SEES e Set ee da A e 2 301 9 3 4 1 Constraint solving With plugins e 301 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 xvii 10 What to do when something goes wrong 10 1 When the compiler does the wrong thing 10 2 When your program does the wrong thing 11 Other Haskell utility programs 11 1 Yacc for Haskell happy 11 2 Writing Haskell interfaces
514. orted abstractly i e T e When an import statement hides an entity that is not exported Causes a warning to be emitted if a literal will overflow e g 300 Wora8 fwarn overflowed literaFwarn empty enumerations Causes a warning to be emitted if an enumeration is empty e g 5 3 fwarn lazy unlifted bindings This flag is a no op and will be removed in GHC 7 10 fwarn duplicate constraints Have the compiler warn about duplicate constraints in a type signature For example 38 e e Show e le e gt a gt a The warning will indicate the duplicated Eq a constraint This option is on by default fwarn duplicate exports Have the compiler warn about duplicate entries in export lists This is useful information if you maintain large export lists and want to avoid the continued export of a definition after you ve deleted one mention of it in the export list This option is on by default fwarn hi shadowing Causes the compiler to emit a warning when a module or interface file in the current directory is shadowing one with the same module name in a library or other directory fwarn identities Causes the compiler to emit a warning when a Prelude numeric conversion converts a type T to the same type T such calls are probably no ops and can be omitted The functions checked for are toInteger toRational fromIntegral and realToFrac fwarn implicit prelude Have the compiler warn if the Prel
515. osely follows the original translation as described in the paper A recursive do for Haskell which in turn is based on the work Value Recursion in Monadic Computations Furthermore GHC extends the syntax described in the former paper with a lower level syntax flagged by the rec keyword as we describe next 7 3 12 1 Recursive binding groups The flag XRecursiveDo also introduces a new keyword rec which wraps a mutually recursive group of monadic statements inside a do expression producing a single statement Similar to a let statement inside a do variables bound in the rec are visible throughout the rec group and below it For example compare alo El Teete har do a lt getChar Pp dis ml E ae 9 fee wil lt E E 2 a O geil a A E iil E pewien ei a cA a rerio l ph 2A The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 164 327 In both cases r 1 and r2 are available both throughout the 1et or rec block and in the statements that follow it The difference is that let is non monadic while rec is monadic In Haskell let is really let rec of course The semantics of rec is fairly straightforward Whenever GHC finds a rec group it will compute its set of bound variables and will introduce an appropriate call to the underlying monadic value recursion operator mf ix belonging to the MonadFix class Here is an example mes la lt face gt oy C lt gt mba NN Rd e gt Elo 1 la lt
516. ossibly different machines Thus a process can create a reference and send it to another process that can resolve it to e With this extension turned on stat ic is no longer a valid identifier Static pointers were first proposed in the paper Towards Haskell in the cloud Jeff Epstein Andrew P Black and Simon Peyton Jones Proceedings of the 4th ACM Symposium on Haskell pp 118 129 ACM 2011 7 21 1 Using static pointers Each reference is given a key which can be used to locate it at runtime with unsafeLookupStaticPtr which uses a global and immutable table called the Static Pointer Table The compiler includes entries in this table for all static forms found in the linked modules The value can be obtained from the reference via deRefStaticPtr The body e of a static e expression must be a closed expression That is there can be no free variables occurring in e i e lambda or let bound variables bound locally in the context of the expression All of the following are permissible aie 88 Toe gt Inte ie Se Es ae dl sit Giegicale dl ref2 static inc Teng Siecieme ame 1 rers tatie Qee gt a Pp 1d al Ss TE ref5 y static let x 1 in x The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 259 327 While the following definitions are rejected ref let x 1 in static x ref7 y static let x 1 in y 7 21 2 Static semantics of static pointers Informally if
517. ote carefully the reinitializeGlobals call at the beginning of the installation function Due to bugs in the windows linker dealing with 1ibghc this call is necessary to properly ensure compiler plugins have the same global state as GHC at the time of invocation Without reinitializeGlobals compiler plugins can crash at runtime because they may require state that hasn t otherwise been initialized In the future when the linking bugs are fixed reinitializeGlobals will be deprecated with a warning and changed to do nothing 9 3 3 Core plugins in more detail CoreToDo is effectively a data type that describes all the kinds of optimization passes GHC does on Core There are passes for simplification CSE vectorisation etc There is a specific case for plugins CoreDoPluginPass String gt Pl uginPass gt CoreToDo which should be what you always use when inserting your own pass into the pipeline The first parameter is the name of the plugin and the second is the pass you wish to insert CoreM is a monad that all of the Core optimizations live and operate inside of A plugin s installation function install in the above example takes a list of CoreToDos and returns a list of CoreToDo Before GHC begins compiling modules it enumerates all the needed plugins you tell it to load and runs all of their installation functions initially on a list of passes that GHC specifies itself After doing this for every plugin the final list of
518. ould allocate starting at the 0 5Gb mark The default is to use the OS s built in support for allocating memory in the low 2Gb if available e g mmap with MAP_32BIT on Linux or otherwise xm40000000 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 98 327 xqsize Default 100k This option relates to allocation limits for more about this see enableAllocationLimit When a thread hits its allocation limit the RTS throws an exception to the thread and the thread gets an additional quota of allocation before the exception is raised again the idea being so that the thread can execute its exception handlers The xq controls the size of this additional quota 4 17 3 RTS options to control the garbage collector There are several options to give you precise control over garbage collection Hopefully you won t need any of these in normal operation but there are several things that can be tweaked for maximum performance Asize Default 512k Set the allocation area size used by the garbage collector The allocation area actually generation 0 step 0 is fixed and is never resized unless you use H below Increasing the allocation area size may or may not give better performance a bigger allocation area means worse cache behaviour but fewer garbage collections and less promotion With only 1 generation G1 the A option specifies the minimum allocation area since the actual size of the alloc
519. ow the two arguments to have different types This then is an example of a multiple parameter class that does actually work quite well in practice without ambiguity problems There is however a catch This version of the Collects class is nowhere near as general as the original class seemed to be only one of the four instances for Collects given above can be used with this version of Collects because only one of them the instance for lists has a collection type that can be written in the form c e for some type constructor c and element type e 7 6 2 2 2 Adding functional dependencies To get a more useful version of the Collects class Hugs provides a mechanism that allows programmers to specify dependencies between the parameters of a multiple parameter class For readers with an interest in theoretical foundations and previous work The use of dependency information can be seen both as a generalization of the proposal for parametric type classes that was put forward by Chen Hudak and Odersky or as a special case of Mark Jones s later framework for improvement of qualified types The underlying ideas are also discussed in a more theoretical and abstract setting in a manuscript implparam where they are identified as one point in a general design space for systems of implicit parameterization To start with an abstract example consider a declaration such as class C a b where which tells us simply that C can be thought of as
520. oxy types type inference for higher rank types and impred icativity which appeared at ICFP 2006 7 13 8 Lexically scoped type variables GHC supports lexically scoped type variables without which some type signatures are simply impossible to write For example B 38 forall e leal Tal SS where ye 2s lel ys reverse xs The type signature for f brings the type variable a into scope because of the explicit forall Section 7 13 8 2 The type variables bound by a forall scope over the entire definition of the accompanying value declaration In this example the type variable a scopes over the whole definition of f including over the type signature for ys In Haskell 98 it is not possible to declare a type for ys a major benefit of scoped type variables is that it becomes possible to do so Lexically scoped type variables are enabled by XScopedTypeVariables This flag implies XRelaxedPolyRec 7 13 8 1 Overview The design follows the following principles e A scoped type variable stands for a type variable and not for a type This is a change from GHC s earlier design Furthermore distinct lexical type variables stand for distinct type variables This means that every programmer written type signature including one that contains free scoped type variables denotes a rigid type that is the type is fully known to the type checker and no inference is involved Lexical type variables may be alpha renamed freely without changin
521. passes is given to the optimizer and are run by simply going over the list in order You should be careful with your installation function because the list of passes you give back isn t questioned or double checked by GHC at the time of this writing An installation function like the following install CommandLineOption gt Coretolol gt CoreM CoreToDo install rere 1s certainly valid but also certainly not what anyone really wants 9 3 3 1 Manipulating bindings In the last section we saw that besides a name a CoreDoPluginPass takes a pass of type PluginPass A PluginPass is a synonym for ModGuts gt CoreM ModGuts ModGut s is a type that represents the one module being compiled by GHC at any given time A ModGuts holds all of the module s top level bindings which we can examine These bindings are of type CoreBind and effectively represent the binding of a name to body of code Top level module bindings are part of a ModGuts in the field mg_binds Implementing a pass that manipulates the top level bindings merely needs to iterate over this field and return a new ModGuts with an updated mg_binds field Because this is such a common case there is a function provided named bindsOnlyPass which lifts a function of type CoreBind gt CoreM CoreBind totype ModGuts gt CoreM ModGuts Continuing with our example from the last section we can write a simple plugin that just prints out the name of all the non
522. performance improvements over the 7 8 branch 1 5 1 Highlights The highlights since the 7 8 branch are GHC has implemented The Applicative Monad Proposal meaning the Applicative typeclass is now a superclass of Monad This is a breaking change and your programs will need to be updated Please see the GHC 7 10 Migration Guide on the GHC wiki GHC has implemented the Burning Bridges Proposal meaning that many of the combinators in Prelude are now re exported from more generic modules such as Data Traversable rather than exporting custom less generic versions This is a change that may require updates to your program Please see the GHC 7 10 Migration Guide on the GHC wiki GHC now has support for partial type signatures which give you the ability to add holes to a type signature that the compiler can later infer For more see Section 7 15 The integer gmp package has been completely rewritten from the ground up The primary change in this rewrite is that GHC compiled programs that link to GMP no longer hook GMP allocation routines to create an Integer on the raw Haskell heap Instead integer gmp now allocates all memory in Haskell code and talks to GMP via normal FFI imports like other C code The practical side effect of this is that C libraries which bind to GMP such as MPFR or FLINT no longer need careful or impossible hacks to be used inside a GHC compiled program via the FFI GMP is treated just li
523. perthreading cores should be counted or not is an open question please feel free to experiment and let us know what results you find The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 95 327 Be careful when using all the processors in your machine if some of your processors are in use by other programs this can actually harm performance rather than improve it Setting N also has the effect of enabling the parallel garbage collector see Section 4 17 3 The current value of the N option is available to the Haskell program via Control Concurrent getNumCapabi lities and it may be changed while the program is running by calling Control Concurrent setNumCapabil ities The following options affect the way the runtime schedules threads on CPUs qa Use the OS s affinity facilities to try to pin OS threads to CPU cores When this option is enabled the OS threads for a capability i are bound to the CPU core i using the API provided by the OS for setting thread affinity e g on Linux GHC uses sched_setaffinity Depending on your workload and the other activity on the machine this may or may not result in a performance improve ment We recommend trying it out and measuring the difference qm Disable automatic migration for load balancing Normally the runtime will automatically try to schedule threads across the available CPUs to make use of idle CPUs this option disables that behaviour Note that mi
524. pes as well as be generalised over and behave as type variables In the first example above _x is generalised over and is effectively replaced by a fresh type variable w_x In the second example _x is unified with the Bool type and as Bool implements the Show type class the constraint Show Bool can be simplified away By default GHC as the Haskell 2010 standard prescribes parses identifiers starting with an underscore in a type as type vari ables To treat them as named wildcards the KNamedWildCards flag should be enabled The example below demonstrated the effect too 2 a A foo _ False Compiling this program without enabling XNamedWildCards produces the following error message complaining about the type variable _a no matching the actual type Bool MOSSOS Couldn t match expected type _a with actual type Bool a is a rigid type variable bound by the type signature for foo _a gt _a at Test hs 4 8 Relevant bindings include foo _a gt _a bound at Test hs 4 1 In the expression False In an equation for foo foo _ False Compiling this program with KNamedWildCards enabled produces the following error message reporting the inferred type of the named wildcard _ a Test hs 4 8 Warning Found hole _a with type Bool la cas tos Silcmeturze oz OG E a gt El 7 15 1 3 Extra Constraints Wildcard The third kind of wildcard is the extra constraints wildcard The presence of an
525. ping intermediate files Section 4 7 5 Flag Description Static Dynamic Reverse keep hc file or retain intermediate hc Ame keep hc files files y keep llvm file or retain intermediate LLVM a keep 1lvm files 11 files y seep S tl leor retain intermediate s files dynamic keep s files k RES retain all intermediate a P R temporary files y 4 19 6 Temporary files Section 4 7 6 Flag Description Static Dynamic Reverse Empate set the directory for e temporary files The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 111 327 4 19 7 Finding imports Section 4 7 3 Flag Description Static Dynamic Reverse ae add dir dir2 etc to idirlidir2 dynamic set import path Empty the i t direct A S a a dynamic set list 4 19 8 Interface file options Section 4 7 7 Flag Description Static Dynamic Reverse A Dump the new interface to duarte g stdout Sino editis Show the differences vs the dynamit g old interface ddump minimal Dump a minimal set of 3 dynamic imports imports show iface fil See Section 4 5 4 19 9 Recompilation checking Section 4 7 8 Flag Description Static Dynamic Reverse Turn off recompilation checking This is implied fforce recomp by any ddump X option dynamic fno force recomp when compiling a single fi
526. ports from these initial modules It will then attempt to compile each module which is out of date and finally if there is a Main module the program will also be linked into an executable The main advantages to using ghc make over traditional Makefi les are e GHC doesn t have to be restarted for each compilation which means it can cache information between compilations Com piling a multi module program with ghc make can be up to twice as fast as running ghc individually on each source file e You don t have to write a Makefile e GHC re calculates the dependencies each time it is invoked so the dependencies never get out of sync with the source e Using the j flag you can compile modules in parallel Specify jN to compile n jobs in parallel Any of the command line options described in the rest of this chapter can be used with make but note that any options you give on the command line will apply to all the source files compiled so if you want any options to apply to a single source file only you ll need to use an OPTIONS_GHC pragma see Section 4 2 2 If the program needs to be linked with additional objects say some auxiliary C code then the object files can be given on the command line and GHC will include them when linking the executable For backward compatibility with existing make scripts when used in combination with c the linking phase is omitted same as make no link Note that GHC can
527. possible It is equivalent to adding an UNPACK pragma to every strict constructor field see Section 7 22 11 This option is a bit of a sledgehammer it might sometimes make things worse Selectively unboxing fields by using UNPACK pragmas might be better An alternative is to use funbox strict fields to turn on unboxing by default but disable it for certain constructor fields using the NOUNPACK pragma see Section 7 22 12 funfolding creation threshold n Default 750 Governs the maximum size that GHC will allow a function unfolding to be An unfolding has a size that reflects the cost in terms of code bloat of expanding aka inlining that unfolding at a call site A bigger function would be assigned a bigger cost Consequences a nothing larger than this will be inlined unless it has an INLINE pragma b nothing larger than this will be spewed into an interface file Increasing this figure is more likely to result in longer compile times than faster code The funfolding use thre shold is more useful funfolding dict discount n Default 30 funfolding fun discount n Default 60 funfolding keeness factor n Default 1 5 funfolding use threshold n Default 60 This is the magic cut off figure for unfolding aka inlining 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 a
528. processor options Section 4 12 3 Flag Description Static Dynamic Reverse B Run the C pre processor on donde i CPP Haskell source files y Define a symbol in the C y Dsymbol value dynamic Usymbol pre processor Undefine a symbol in the C Usymbol dynamic pre processor Add dir to the directory Idir search list for include dynamic files 4 19 20 Code generation options Section 4 12 5 Flag Description Static Dynamic Reverse E Use the native code dmi Hien generator eae Compile using the LLVM damis asm code generator fno code Omit code generation dynamic fwrite interfac Always write interface files dynamic fbyte code Generate byte code dynamic fobject cod Generate object code dynamic 4 19 21 Linking options Section 4 12 6 Flag Description Static Dynamic Reverse Generate a shared library shared as opposed to an dynamic executable The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 126 327 Flag Description Static Dynamic Reverse staticlib On Darwin OS X iOS only generate a standalone static library as opposed to an executable This is the usual way to compile for iOS dynamic fPIC Generate position independent code where available dynamic dynamic Use dynamic Haskell libraries if available dynamic dynamic too Build dynamic object files as well as static object files during compilation
529. profiling e 139 5 4 3 Biographical Profiling 2 2 2 00 0 000002 e ee ee 139 54 4 Actual Memory residency sori e a Sy taiee eo AC awh Eee fa AAA a 140 5 5 hp2ps heap profile to PostScript 2 a 140 5 5 1 Manipulating the hp file 2 2 0 0 0 000000000000 0000 141 5 5 2 Zooming in on regions of your profile e 141 5 5 3 Viewing the heap profile of a running program 1 2 ee 142 5 5 4 Viewing a heap profileinrealtime 0 0 0 0 000 pee ee 142 5 6 Profiling Parallel and Concurrent Programs oaoa 142 5 7 Observing Code Coverage e errades eker c trete kedo eek keene 143 5 7 1 A small example Reciprocation 0 00 ee ee 143 5 7 2 Options for instrumenting code for coverage 2 2 e 144 5 7 3 The bpe toolkit 34 5 6440 o a e A eee 144 DLL Ape report cones 5 e A O A A E AR e e 145 32 hpemarmkup at a RADA AA AR ox 145 5 3 3 A IN 146 A o A EN 146 S323 DPCMaP sac a SRR RARE ARERR ER a ER GER A R Ea Oe RS wee ek 146 5 7 3 6 hpc overlay andhpe draft 2 ee 147 5 7 4 Caveats and Shortcomings of Haskell Program Coverage o 147 5 8 Using ticky ticky profiling for implementors s oa e 147 6 Advice on sooner faster smaller thriftier 148 6 1 Sooner producing a program more quickly b eee eee 148 6 2 Faster producing a program that runs quicker
530. program to give a different answer than it would normally and hence it won t cause any exceptions to be raised infinite loops or further breakpoints to be triggered see Section 2 5 3 Rather than forcing thunks print binds each thunk to a fresh variable beginning with an underscore in this case _t 1 The flag fprint evld with show instructs print to reuse available Show instances when possible This happens only when the contents of the variable being inspected are completely evaluated If we aren t concerned about preserving the evaluatedness of a variable we can use force instead of print The force command behaves exactly like print except that it forces the evaluation of any thunks it encounters 6 We originally provided bindings for all variables in scope rather than just the free variables of the expression but found that this affected performance considerably hence the current restriction to just the free variables The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 26 327 Sor SARIS ao Nenias giteweee lee left 4 0 3 1 Now since force has inspected the runtime value of left it has reconstructed its type We can see the results of this type reconstruction qsort hs 2 15 46 Main gt show bindings _result Integer e 323 antes left Integer right Integer MA neg ea Not only do we now know the type of left but all the other partial types have
531. program was doing when it evaluated head Implementation details aside the function names in the stack should hopefully give you enough clues to track down the bug See also the function t raceStack in the module Debug Trace for another way to view call stacks Z Turn off update frame squeezing at garbage collection time There s no particularly good reason to turn it off except to ensure the accuracy of certain data collected regarding thunk entry counts 4 17 8 Getting information about the RTS It is possible to ask the RTS to give some information about itself To do this use the info flag e g a out RTS info 1 i 1 1 1 WEIS IMTS UTS GH wersten 6 1 KRIS wany Sp te SHA Ja Host platform x86_64 unknown linux Host architecture x86_64 insiosic OS Y Er oa Host vendor unknown Build platform x86_64 unknown linux Build architecture x66 84 Geva le OSW Viata Build vendor unknown Target platform x86_64 unknown linux Target architecture x86_64 lavage OS Mili Target vendor unknown Word size 64 Compiler unregisterised NO Tables next to code YES The information is formatted such that it can be read as a of type String String Currently the following fields are present GHC GHC RTS R
532. property in the package database please refer to Section 4 9 7 29 5 Safe Haskell Inference In the case where a module is compiled without one of XSafe XTrustworthy or XUnsafe being used GHC will try to figure out itself if the module can be considered safe This safety inference will never mark a module as trustworthy only as either unsafe or as safe GHC uses a simple method to determine this for a module M If M would compile without error under the XSafe flag then M is marked as safe If M would fail to compile under the XSafe flag then it is marked as unsafe When should you use Safe Haskell inference and when should you use an explicit XSafe flag The later case should be used when you have a hard requirement that the module be safe That is the use cases outlined and the purpose for which Safe Haskell is intended compiling untrusted code Safe inference is meant to be used by ordinary Haskell programmers Users who probably don t care about Safe Haskell The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 286 327 Say you are writing a Haskell library Then you probably just want to use Safe inference Assuming you avoid any unsafe features of the language then your modules will be marked safe This is a benefit as now a user of your library who may want to use it as part of an API exposed to untrusted code can use the library without change If there wasn t safety inference then either the writ
533. ption pass oe vee dynamic optimiser ion to the LLVM optic option pan PERTON oe dynamic compiler es pass option to the i opta option assembler dynamic optl option pass option to the linker dynamic optdll option pass opt rent Me DLE dynamic generator optwindres option pass optiontowindres dynamic 4 19 25 Platform specific options Section 4 16 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 129 327 Flag Description Static Dynamic Reverse EAT x86 only Use SSE2 for ise g floating point 4 19 26 Compiler debugging options Section 4 18 Flag Description Static Dynamic Reverse ES Turn on internal sanity Aaa i checking Jd mp to fii Dump to files instead of die stdout ddump asm Dump assembly dynamic ddump bcos Dump interpreter byte code dynamic ddump cmm Dump C output dynamic Print a one line summary of ddump core stats bae dynamic il program at the end of the y optimisation pipeline ddump cse Dump CSE output dynamic ddump deriv Dump deriving output dynamic ddump ds Dump desugarer output dynamic D f j ddump foreign ump Ore EAPOEE dynamic stubs dE Dump after instrumentation drene g for program coverage ddump inlinings Dump inlining info dynamic damn Dump LLVM intermediate aca g code diompeononte
534. r s Guide Version 7 10 2 180 327 7 4 6 Existentially quantified data constructors The idea of using existential quantification in data type declarations was suggested by Perry and implemented in Hope Nigel Perry The Implementation of Practical Functional Programming Languages PhD Thesis University of London 1991 It was later formalised by Laufer and Odersky Polymorphic type inference and abstract data types TOPLAS 16 5 pp1411 1430 1994 It s been in Lennart Augustsson s hbe Haskell compiler for several years and proved very useful Here s the idea Consider the declaration data Foo forall a MkFoo a a gt Bool Nil The data type Foo has two constructors with types MER OO s forall es gt la gt Bool e bac Nil 8 OO Notice that the type variable a in the type of MkFoo does not appear in the data type itself which is plain Foo For example the following expression is fine MkFoo 3 even MkFoo c isUpper Foo Here MkFoo 3 even packages an integer with a function even that maps an integer to Bool and MkFoo c isUp per packages a character with a compatible function These two things are each of type Foo and can be put in a list What can we do with a value of type Foo In particular what happens when we pattern match on MkF oo f MkFoo val Ib 277 Since all we know about val and fn is that they are compatible the only useful thing we can do with them is to apply fn to val
535. r else it will link the objects named on the command line to produce an executable The available mode flags are ghc ghc ghc ghc ghc ghc ghc ghc interactive Interactive mode which is also available as ghci Interactive mode is described in more detail in Chapter 2 make In this mode GHC will build a multi module Haskell program automatically figuring out dependencies for itself If you have a straightforward Haskell program this is likely to be much easier and faster than using make Make mode is described in Section 4 5 1 This mode is the default if there are any Haskell source files mentioned on the command line and in this case the make option can be omitted e expr Expression evaluation mode This is very similar to interactive mode except that there is a single expression to evaluate expr which is given on the command line See Section 4 5 2 for more details E ghc Cghe Sghe c This is the traditional batch compiler mode in which GHC can compile source files one at a time or link objects together into an executable See Section 4 5 3 M Dependency generation mode In this mode GHC can be used to generate dependency information suitable for use ina Makefile See Section 4 7 12 mk d11 DLL creation mode Windows only See Section 12 6 1 help ghc Cause GHC to spew a long usage message to standard output and then exit show iface file Read the interface in file and dump it as
536. r is bound using the standard let or where binding forms For example we define the min function by binding cmp mia lal gt a min let cmp lt in least A group of implicit parameter bindings may occur anywhere a normal group of Haskell bindings can occur except at top level That is they can occur in a let including in a list comprehension or do notation or pattern guards or a where clause Note the following points e An implicit parameter binding group must be a collection of simple bindings to implicit style variables no function style bindings and no type signatures these bindings are neither polymorphic or recursive e You may not mix implicit parameter bindings with ordinary bindings in a single let expression use two nested lets instead In the case of where you are stuck since you can t nest where clauses e You may put multiple implicit parameter bindings in a single binding group but they are not treated as a mutually recursive group as ordinary let bindings are Instead they are treated as a non recursive group simultaneously binding all the implicit parameter The bindings are not nested and may be re ordered without changing the meaning of the program For example consider Tu lee 4 Gx See Sy Perle Silao j alia Pec cP By The use of x in the binding for y does not see the binding for x so the type of f is in 82 Re SINE gt dae gt oe The Glorious Glasgow Haskell Compilat
537. ra dependencies that declare that files with suffix lt suf gt _ lt osuf gt depend on interface files with suffix lt suf gt _hi or for SOURCE imports on hi boot Multiple dep suffix flags are permitted For example dep suffix a dep suffix b will make dependencies for hs on hi a_hson a_hi and b_hs on b_hi Useful in conjunction with NoFib ways exclude module lt file gt Regard lt file gt as stable i e exclude it from having dependencies on it include pkg deps Regard modules imported from packages as unstable i e generate dependencies on any imported package modules including Prelude and all other standard Haskell libraries Dependencies are not traced recursively into packages dependencies are only generated for home package modules on external package modules directly imported by the home package module This option is normally only used by the various system libraries 4 7 13 Orphan modules and instance declarations Haskell specifies that when compiling module M any instance declaration in any module below M is visible Module A is below M if A is imported directly by M or if A is below a module that M imports directly In principle GHC must therefore read the interface files of every module below M just in case they contain an instance declaration that matters to M This would be a disaster in practice so GHC tries to be clever In particular if an instance declaration is in the sam
538. ragments are incorrect E MEE OO Fa S a Here the type bound by MkFoo escapes because a is the result of 1 One way to see why this is wrong is to ask what type 1 has EL s3 FOO gt G Weird What is this a in the result type Clearly we don t mean this ii 83 corall a Foo gt a Mong The original program is just plain wrong Here s another sort of error f2 Bazl a b Bazl p q a q It s ok to say a b or p q but a q is wrong because it equates the two distinct types arising from the two Baz 1 construc tors e You can t pattern match on an existentially quantified constructor in a let or where group of bindings So this is illegal f3 x a b where Bazl ab x Instead use a case expression f3 x case x of Bazl ab gt a b In general you can only pattern match on an existentially quantified constructor in a case expression or in the patterns of a function definition The reason for this restriction is really an implementation one Type checking binding groups is already a nightmare without existentials complicating the picture Also an existential pattern binding at the top level of a module doesn t make sense because it s not clear how to prevent the existentially quantified type escaping So for now there s a simple to state restriction We ll see how annoying it is e You can t use existential quantification for newt ype declarations So this is illegal newt
539. raries don t clobber the normal ones Similarly the hisuf suffix will change the hi file suffix for non system interface files see Section 4 7 7 Finally the option hcsuf suffix will change the hc file suffix for compiler generated intermediate C files The hisuf osuf game is particularly useful if you want to compile a program both with and without profiling in the same directory You can say quee to get the ordinary version and CIM oon OSU PrO O LSV joo nl oO Emite adL to get the profiled version 4 7 5 Keeping Intermediate Files The following options are useful for keeping certain intermediate files around when normally GHC would throw these away after compilation keep hc file keep hc files Keep intermediate hc files when doing hs to o compilations via C NOTE hc files are only generated by unregisterised compilers keep llvm file keep llvm files Keep intermediate 11 files when doing hs to o compilations via LLVM NOTE 11 files aren t generated when using the native code generator you may need to use f11vm to force them to be produced keep s file keep s files Keep intermediate s files keep tmp files Instructs the GHC driver not to delete any of its temporary files which it normally keeps in tmp or possibly elsewhere see Section 4 7 6 Running GHC with v will show you what temporary files were generated along the way 4 7 6 Redirecting temporary files tmpdir
540. ration one can quantify the types of the constructor arguments Here are several examples deta T a TL forall ba b gt b gt b a data MonadT m MkMonad return forall a a gt ma bing ss forall a b ma gt le gt m by gt w o newtype Swizzle MkSwizzle forall a Ord a gt a gt a The constructors have rank 2 types tl forall a forall bh o 1 gt lo gt a gt Ta MkMonadik oa ora A Mo gt Gorell a lo mea gt la gt m lo gt im la gt MonadT m MkSwizzle forall a Ord a gt a gt a gt Swizzle The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 232 327 In earlier versions of GHC it was possible to omit the foral1 in the type of the constructor if there was an explicit context For example newtype Swizzle MkSwizzle Ord a gt a gt a As of GHC 7 10 this is deprecated The fwarn context quantification flag detects this situation and issues a warning In GHC 7 12 declarations such as Mk Swizzle will cause an out of scope error As for type signatures implicit quantification happens for non overloaded types too So if you write this Cou WS HS Sah a e it s just as if you had written this Ces nomal as le gt a gt A That is since the type variable a isn t in scope it s implicitly universally quantified You construct values of types T1 MonadT Swizzle by applying the construct
541. ration splices both typed and untyped as they happen As with all dump flags the default is for this output to be sent to stdout For a non trivial program you may be interested in combining this with the ddump to file flag see Section 4 18 1 For each file using Template Haskell this will show the output ina dump splices file The flag dth dec file shows the expansions of all top level TH declaration splices both typed and untyped in the file M th hs where M is the name of the module being compiled Note that other types of splices expressions types and patterns are not shown Application developers can check this into their repository so that they can grep for identifiers that were defined in Template Haskell This is similar to using ddump to file with ddump splices but it always generates a file instead of being coupled to ddump to file The format is also different it does not show code from the original file instead it only shows generated code and has a comment for the splice location of the original file Below is a sample output of ddump splices TH_pragma hs 6 4 8 26 Splicing declarations fo oo 53 bye gt Mime foo x x 111 LOO 28 Lmt gt dae foo x x 1 Below is the output of the same sample using dth dec fil TEA Es qn as 0 24 o AON Saleno de e ltotratalons FOO 38 Ime gt Imt foo x x 1 7 17 4 A Template Haskell Worked Example To help you get over the confid
542. re building a large system with significant doses of conditional compilation you really shouldn t need it Dsymbol value Define macro symbol in the usual way NB does not affect D macros passed to the C compiler when compiling via C For those use the optc Dfoo hack see Section 4 12 2 Usymbol1 Undefine macro symbol in the usual way Idir 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 1hs files The symbols defined by GHC are listed below To check which symbols are defined by your local GHC installation the following trick is useful Cine z CjstP clil cg foo iis cat foo hspp you need a file foo hs but it isn t actually used __GLASGOW_HASKELL For version x y z of GHC the value of __GLASGOW_HASKELL__ is the integer xyy if y is a single digit then a leading zero is added so for example in version 6 2 of GHC __GLASGOW_HASKELL__ 602 More information in Section 1 4 T 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 __NHC__ for nhc98 and__HBC__ for hbc 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 1hs
543. recognised pragmas 61 fwarn unsupported calling conventions 62 fwarn unticked promoted constructors 64 fwarn unused binds 65 fwarn unused do bind 65 fwarn unused imports 65 fwarn unused matches 65 fwarn warnings deprecations 61 fwarn wrong do bind 66 fwrite interface 88 ghci script 40 global package db 70 h lt break down gt 140 hC RTS option 138 hT RTS option 102 hb RTS option 137 138 hc RTS option 137 138 hesuf 53 hd RTS option 137 138 hide package 68 hidir 52 hisuf 53 hm RTS option 137 138 hr The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 322 327 RTS option 137 138 hy RTS option 137 138 i 138 idirs 51 ignore dot ghci 40 ignore package 68 k RTS option 99 kc RTS option 99 keep hc file 53 keep hc files 53 keep llvm file 53 keep llvm files 53 keep s file 53 keep s files 53 keep tmp files 53 1 88 RTS option 102 m RTS option 100 m options 95 main is 89 msse2 318 n RTS option 98 no auto link packages 68 no fprof auto 136 no global package db 70 no hs main 89 291 no user package db 70 0 52 odir 52 ohi 52 optE 85 optL 85 optP 85 opta 85 optc 85 optdll 85 optl 85 optlc 85 optlo 85 optwindres 85 osuf 53 248 outputdir 52 p 136 RTS option 132 pa 136 package 67 88 package db 70 73 package id 68 pgmF 8
544. relude gt 0 1 3 6 Prelude gt To alleviate this issue GHCi commands can be split over multiple lines by wrapping them in and each on a single line of its own Prelude gt Prelude let g op n Prelude p Cj in Unse In Yoo G Cio m T Prelude Prelude Prelude romam i il sd 6 al Such multiline commands can be used with any GHCi command and the lines between and are simply merged into a single line for interpretation That implies that each such group must form a single valid command when merged and that no layout rule is used The main purpose of multiline commands is not to replace module loading but to make definitions in ghci files see Section 2 9 more readable and maintainable Any exceptions raised during the evaluation or execution of the statement are caught and printed by the GHCi command line interface for more information on exceptions see the module Control Except ion in the libraries documentation Every new binding shadows any existing bindings of the same name including entities that are in scope in the current module context WARNING temporary bindings introduced at the prompt only last until the next load or reload command at which time they will be simply lost However they do survive a change of context with module the temporary bindings just move to the new location HINT To get a list of the bindings currently in scope use the show
545. report containing the actual time and allocation data as well Not used much The pa option produces the most detailed report containing all cost centres in addition to the actual time and allocation data Vsecs Sets the interval that the RTS clock ticks at which is also the sampling interval of the time and allocation profile The default is 0 02 seconds xc This option causes the runtime to print out the current cost centre stack whenever an exception is raised This can be particularly useful for debugging the location of exceptions such as the notorious Prelude head empty list error See Section 4 17 7 5 4 Profiling memory usage In addition to profiling the time and allocation behaviour of your program you can also generate a graph of its memory usage over time This is useful for detecting the causes of space leaks when your program holds on to more memory at run time that it needs to Space leaks lead to slower execution due to heavy garbage collector activity and may even cause the program to run out of memory altogether To generate a heap profile from your program 1 Compile the program for profiling Section 5 2 2 Run it with one of the heap profiling options described below eg h for a basic producer profile This generates the file prog hp 3 Run hp2ps to produce a Postscript file prog ps The hp2ps utility is described in detail in Section 5 5 4 Display the heap profile using a postscript viewer suc
546. riable just like a Thus in Haskell 98 you can say e rr CGY ry Just like type T a a a E 8 T Toe gt Ime x y x As you can see using operators in this way is not very useful and Haskell 98 does not even allow you to write them infix The language XTypeOperators changes this behaviour e Operator symbols become type constructors rather than type variables e Operator symbols in types can be written infix both in definitions and uses for example datata b Pius tao type Foo Int Bool e There is now some potential ambiguity in import and export lists for example if you write import M do you mean the function or the type constructor The default is the former but with XExplicitNamespaces which is implied by XExplicitTypeOperators GHC allows you to specify the latter by preceding it with the keyword type thus import M type See Section 7 3 26 4 e The fixity of a type operator may be set using the usual fixity declarations but as in Section 7 4 3 the function and type constructor share a single fixity 7 4 5 Liberalised type synonyms Type synonyms are like macros at the type level but Haskell 98 imposes many rules on individual synonym declarations With the XLiberalTypeSynonyms extension GHC does validity checking on types only after expanding type synonyms That means that GHC can be very much more liberal about type synonyms than Haskell 98 e You can w
547. rite a forall including overloading in a type synonym thus The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 179 327 TYPORD ES Cac ce O ADS OS me Oia ar ES triad E 28 Disceua el fxy x show y DESEAR MAS SEIN ES JS TS e If you also use XUnboxedTuples you can write an unboxed tuple in a type synonym type Pr Int Int It gs Tar gt 1250 h x x x 4 e You can apply a type synonym to a forall type type Foo a a gt a gt Bool fee oo romeli on 1o20 After expanding the synonym f has the legal in GHC type Eto Gorell lgs bas gt MOTA LU gt gt OG e You can apply a type synonym to a partially applied type synonym EY PENE ST SIC O E E O type Id x x foo Generic Id After expanding the synonym foo has the legal in GHC type OO 838 Formal sk e gt 15 GHC currently does kind checking before expanding synonyms though even that could be changed After expanding type synonyms GHC does validity checking on types looking for the following mal formedness which isn t detected simply by kind checking e Type constructor applied to a type involving for alls if XImpredicativeTypes is off e Partially applied type synonym So for example this will be rejected type Pr forall a a h Esa he because GHC does not allow type constructors applied to for all types The Glorious Glasgow Haskell Compilation System Use
548. rmally using GHCi users can inspect the inferred type signatures of all top level bindings However this method is less convenient with terms that are not defined on top level or inside complex expressions Holes allow the user to check the type of the term they are about to write To run and test a piece of code containing holes use the fdefer typed holes flag This flag defers errors produced by typed holes and converts them into warnings The result is that typed hole errors are converted into warnings controlled by fwarn typed holes The result is that a hole will behave like undefined but with the added benefits that it shows a warning at compile time and will show another warning message if it gets evaluated This behaviour follows that of the fdefer type errors option which implies fdefer typed holes See Section 7 16 For example compiling the following module with GHC ic a gt f x will fail with the following error hole nhsis2 7 Found hole _ with type a Where a is a rigid type variable bound by the type signature for f a gt a at hole hs 1 6 Relevant bindings include toi a a bound at nole nasze x gge a bound at bolle ns22 73 In the expression _ In an equation for f x Multiple typed holes can be used to find common type variables between expressions For example The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 239 327
549. rmine what parts of their code have been actually executed and which parts have never actually been invoked GHC has an option for generating instrumented code that records code coverage as part of the Haskell Program Coverage HPC toolkit which is included with GHC HPC tools can be used to render the generated code coverage information into human understandable format Correctly instrumented code provides coverage information of two kinds source coverage and boolean control coverage Source coverage is the extent to which every part of the program was used measured at three different levels declarations both top level and local alternatives among several equations or case branches and expressions at every level Boolean coverage is the extent to which each of the values True and False is obtained in every syntactic boolean context ie guard condition qualifier HPC displays both kinds of information in two primary ways textual reports with summary statistics hpc report and sources with color mark up hpc markup For boolean coverage there are four possible outcomes for each guard condition or qualifier both True and False values occur only True only False never evaluated In hpc markup output highlighting with a yellow background indicates a part of the program that was never evaluated a green background indicates an always True expression and a red background indicates an always False one 5 7 1 A small example Reciprocatio
550. rrow As g2 shows the polymorphic type on the left of the function arrow can be overloaded The function 3 has a rank 3 type 1t has rank 2 types on the left of a function arrow The language option XRankNTypes which implies XExplicitForAl11 Section 7 13 1 enables higher rank types That is you can nest foral ls arbitrarily deep in function arrows For example a forall type also called a type scheme including a type class context is legal e On the left or right see 4 for example of a function arrow e As the argument of a constructor or type of a field in a data type declaration For example any of the 1 2 3 g1 g2 above would be valid field type signatures e As the type of an implicit parameter e Ina pattern type signature see Section 7 13 8 The XRankNTypes option is also required for any type with a foral1 or context to the right of an arrow e g f Int gt forall a a gt a org Int gt Ord a gt a gt a Such types are technically rank 1 but are clearly not Haskell 98 and an extra flag did not seem worth the bother The obselete language options XPolymorphicComponents and XRank2Types are synonyms for XRankNTypes They used to specify finer distinctions that GHC no longer makes They should really elicit a deprecation warning but they don t purely to avoid the need to library authors to change their old flags specifciations 7 13 6 1 Examples In a data or newt ype decla
551. rsion so A o B o C o The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 75 327 Using GHC s version number in the shared object name allows different library versions compiled by different GHC versions to be installed in standard system locations e g under nix usr lib To obtain the version number of GHC invoke ghc numeric version and use its output in place of GHCVersion See also Section 4 12 5 on how object files must be prepared for shared object linking To compile a module which is to be part of a new package use the this package key option Section 4 9 1 Failure to use the this package key option when compiling a package will probably result in disaster but you will only discover later when you attempt to import modules from the package At this point GHC will complain that the package name it was expecting the module to come from is not the same as the package name stored in the hi file It is worth noting with shared objects when each package is built as a single shared object file since a reference to a shared object costs an extra indirection intra package references are cheaper than inter package references Of course this applies to the main package as well 49 9 InstalledPackageInfo a package specification A package specification is a Haskell record in particular it is the record InstalledPackageInfo in the module Distribution InstalledPackag which is part of the Cabal package d
552. rty of a package only plays a role when compiling code using GHC s Safe Haskell feature see Section 7 29 with the fpackage trust flag enabled To see which modules are provided by a package use the ghc pkg command see Section 4 9 7 ghc pkg field network exposed modules xposed modules Network BSD Network CGI Network Socket Network URI Network The GHC command line options that control packages are package P This option causes the installed package P to be exposed The package P can be specified in full with its version number e g net work 1 0 or the version number can be omitted if there is only one version of the package installed If there are multiple versions of P installed and hide all packages was not specified then all other versions will become hidden package supports thinning and renaming described in Section 4 9 4 The package P option also causes package P to be linked into the resulting executable or shared object Whether a packages library is linked statically or dynamically is controlled by the flag pair st at ic dynamic In make mode and interactive mode see Section 4 5 the compiler normally determines which packages are required by the current Haskell modules and links only those In batch mode however the dependency information isn t available and explicit package options must be given when linking The one other time you might need to use package to force linking a packa
553. rules will default to String A small example module Main where BMD Orson GHEE sce Sk EES o ite atst q A newtype MyString MyString String deriving Eq Show instance IsString MyString where fromString MyString The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 205 327 greet MyString gt MyString greet hello world greet other other main do print greet hello print great Eo Note that deriving Eq is necessary for the pattern matching to work since it gets translated into an equality comparison 7 6 5 Overloaded lists GHC supports overloading of the list notation Let us recap the notation for constructing lists In Haskell the list notation can be be used in the following seven ways Music liste x x 8 za 52 8 W 8 2 8 I Be ie enumFrom x RW 01 enumFromThen x y Roo Wl enumFromTo x y 2 oo El EMiiromillaciallo Y Z When the OverloadedLists extension is turned on the aforementioned seven notations are desugared as follows Eeo 10 T x TrombistNol de UL za soma SS lt 8 WV amp 4 8 nd Ree tor fromList enumFrom x Kp aol fromList enumFromThen x y Z oo Wl fromList enumFromTo x y ay oo FA fromList enumFromThenTo x y 2 This extension allows programmers to use the list notation for construction of structures like Set Map IntMap Vector Text and
554. s 5 eS ew A ee a eee ee a ee 192 7 6 Class and instances declarations ee 192 761 Class declarations 0 3 2 e bed Pee Aw Se eee eee A Bee 192 7 6 1 1 Multi parameter type Classes 2 2 ee 192 7 6 1 2 The superclasses of a class declaration 2 2 2 2 00 0000 000000000 192 7 6 1 3 Class method types Re ee dea eee ee 193 7 6 1 4 Default method signatures ooa 193 76125 Nullary typeclasseS pe e spaa nanea e ea eRe E E E Yee 194 7 6 2 Functional dependencies o oo ee 194 7 6 2 1 Rules for functional dependencies o oo a 194 7 6 2 2 Background on functional dependencies a 195 7 6 2 2 1 An attempt to use constructor classes o a 196 7 6 2 2 2 Adding functional dependencies a 196 7 6 3 Instance declarations os oec ee 198 ROSE Instance resolulion ss e a patai e e E e den eer ed 5 198 7 6 3 2 Relaxed rules for the instance head noaa e e 198 7 6 3 3 Relaxed rules for instance contexts ee 199 1 6 3 4 UndecidableInstances o o seos ge ek a RR Sa eR a we ae 200 7 6 3 5 Overlapping instances ee 201 7 6 3 6 Instance signatures type signatures in instance declarations 203 7 6 4 Overloaded string literals 204 7 6 Overloaded lists uo ca kee Ree wee eee Sea ee ee ee aw ae ee ae 205 POAC The TSisste classs 4 nue gee AAA as Senta AA s 4 205 765 2 Rebindablesyntax p eo ese PRR
555. s GHC now allows stand alone deriving declarations enabled by XStandaloneDeriving data Foo a Bar a Baz Stri deriving instance Eq a gt EQ ng Foo a The syntax is identical to that of an ordinary instance declaration apart from a the keyword deriving and b the absence of the where part However standalone deriving differs from a deriving clause in a number of important ways e The standalone deriving declaration does not need to be in the same module as the data type declaration But be aware of the dangers of orphan instances Section 4 7 13 e You must supply an explicit context in the example the context is declaration In contrast in a deriving clause attached to a data type declaration the context is inferred Eq a exactly as you would in an ordinary instance e Unlike a deriving declaration attached to a data declaration the instance can be more specific than the data type assuming you also use XFlexiblelnstances Section 7 6 3 3 Consider for example data Foo a Bar a Baz S tring deriving instance Eq a gt Eq Foo a derivino ms tance e El gt This will generate a derived instance for Foo a and Foo Maybe a but other types such as Foo 1 will not be an instance of Eq Int Boo e Unlike a deriving declaration attached to a data declaration GHC does not restrict the form of the data type Instead GHC simply generates the appropriate
556. s When the GADTSynt ax extension is enabled GHC allows you to declare an algebraic data type by giving the type signatures of constructors explicitly For example data Maybe a where Nothing Maybe a Just a gt Maybe a The form is called a GADT style declaration because Generalised Algebraic Data Types described in Section 7 4 8 can only be declared using this form Notice that GADT style syntax generalises existential types Section 7 4 6 For example these two declarations are equivalent data Foo forall a MkFoo a a gt Bool data Foo where MKFoo a gt a gt Bool gt Foo Any data type that can be declared in standard Haskell 98 syntax can also be declared using GADT style syntax The choice is largely stylistic but GADT style declarations differ in one important respect they treat class constraints on the data constructors differently Specifically if the constructor is given a type class context that context is made available by pattern matching For example data Set a where MkSet Eq a gt a gt Set a makeSet Eq a gt a gt Set a makeSet xs MkSet nub xs insert a gt Set a gt Set a insert a MkSet as a elem as MkSet as otherwis MkSet a as A use of MkSet as a constructor e g in the definition of makeSet gives rise toa Eq a constraint as you would expect The new feature is that pattern matching on MkSet as in the definitio
557. s 1s because they allow us to write down the cases we want to consider one at a time independently of each other This structure is hidden in the case version Two of the right hand sides are really the same fail and the whole expression tends to become more and more indented Here is how I would write clunky clunky env varl var2 Just vall lt lookup env varl a Ue velli2 lt gt Nookup enw var vall val2 209 ONC ESCUELAS 2018 SUL o The semantics should be clear enough The qualifiers are matched in order For a lt qualifier which I call a pattern guard the right hand side is evaluated and matched against the pattern on the left If the match fails then the whole guard fails and the next equation is tried If it succeeds then the appropriate binding takes place and the next qualifier is matched in the augmented environment Unlike list comprehensions however the type of the expression to the right of the lt is the same as the type of the pattern to its left The bindings introduced by pattern guards scope over all the remaining guard qualifiers and over the right hand side of the equation Just as with list comprehensions boolean expressions can be freely mixed with among the pattern guards For example i se vi s z eves p wise z lt In y Haskell s current guards therefore emerge as a special case in which the qualifier list has just one element a boolean expression 7 3 8 View patterns View patt
558. s 45 module system recursion 54 modules and filenames 13 monad comprehensions 167 monomorphism restriction warning 64 multicore 90 93 multiprocessor 90 93 N name The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 326 327 package specification 76 native code generator 84 NOINLINE 263 NOTINLINE 263 NOUNPACK 267 O object files 50 optimisation 78 optimise aggressively 79 DPH 79 normally 78 options for profiling 135 GHCi 38 language 152 OPTIONS_GHC 260 OPTIONS_GHC pragma 45 orphan instance 60 orphan instances warning 64 orphan module 60 orphan rule 60 orphan rules warning 64 OutOfHeapHook 97 output directing options 52 overflow Int 317 overlapping patterns warning 64 overloading death to 149 264 266 P package environments 78 package trust 285 package url package specification 76 packages 66 building 74 management 72 using 66 with GHCi 32 parallel list comprehensions 165 parallelism 90 93 94 278 parser generator for Haskell 305 Pattern guards Glasgow extension 156 patterns incomplete 63 patterns overlapping 64 phases changing 85 platform specific options 95 postscript from heap profiles 140 pragma 259 LANGUAGE 260 LINE 264 OPTIONS_GHC 260 pragma RULES 268 pragma SPECIALIZE 264 pragmas 61 pre processing cpp 86 pre processing custom 87 Pre processor options 87 problems 303
559. s JOB DATE SA PL MP LE and ending with END_SAMPLI Ek UNIT VALU E forms a single sample you can think of this as a vertical slice of your heap profile The E_ UNIT form a header Each block of lines starting with BI hp2ps utility should accept any input with a properly formatted header followed by a series of complete samples 5 5 2 Zooming in on regions of your profile EGIN_SA You can look at particular regions of your profile simply by loading a copy of the hp file into a text editor and deleting the unwanted samples The resulting hp file can be run through hp2ps and viewed or printed The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 142 327 5 5 3 Viewing the heap profile of a running program The hp file is generated incrementally as your program runs In principle running hp2ps on the incomplete file should produce a snapshot of your program s heap usage However the last sample in the file may be incomplete causing hp2ps to fail If you are using a machine with UNIX utilities installed it s not too hard to work around this problem though the resulting command line looks rather Byzantine head tgrep nh ENDESAMP IME POO hpa EA CUT ASS E COEN hp2ps gt FOO ps The command fgrep n END_SAMPLE FOO hp finds the end of every complete sample in FOO hp and labels each sample with its ending line number We then select the line number of
560. s containing ghc compiled code This section shows you how to make use of this facility There are two distinct ways in which DLLs can be used You can turn each Haskell package into a DLL so that multiple Haskell executables using the same packages can share the DLL files As opposed to linking the libraries statically which in effect creates a new copy of the RTS and all libraries for each executable produced That is the same as the dynamic linking on other platforms and it is described in Section 4 13 You can package up a complete Haskell program as a DLL to be called by some external usually non Haskell program This is usually used to implement plugins and the like and is described below 12 6 1 Creating a DLL Sealing up your Haskell library inside a DLL is straightforward compile up the object files that make up the library and then build the DLL by issuing a command of the form ghc shared o foo dll bar o baz o wibble a lfooble By feeding the ghc compiler driver the option shared it will build a DLL rather than produce an executable The DLL will consist of all the object files and archives given on the command line A couple of things to notice e By default the entry points of all the object files will be exported from the DLL when using shared Should you want to constrain this you can specify the module definition file to use on the command line as follows gne k shared 9 6000 MBE eis See Microsoft
561. s e g Import and export declarations referring to these operators require an explicit namespace annotation see Section 7 3 26 4 Here is an exampe of using type level numeric literals to provide a safe interface to a low level function import GHC TypeLits import Data Word import Foreign newtype ArrPtr n Nat a ArrPtr Ptr a clearPage ArrPtr 4096 Word8 gt IO clearPage ArrPtr p Here is an example of using type level string literals to simulate simple record operations data Label 1 Symbol Get class Has a lb a 1 gt b where prom 2 El gt close Jl gt 19 data Point Point Int Int deriving Show instance Has Point x Int where from Point x _ _ x instance Has Point y Int where from Point _ y _ y example from Point 1 2 Get Label x 7 10 1 Runtime Values for Type Level Literals Sometimes it is useful to access the value level literal assocaited with a type level literal This is done with the functions nat Val and symbolVal For example The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 223 327 GHC TypeLits gt marvel Proxy Proxy 2 2 These functions are overloaded because they need to return a different result depending on the type at which they are instantiated natVal KnownNat n gt proxy n gt Integer instance KnownNat 0 instance KnownNat 1 instance KnownNat 2 GHC discharges the constraint as soon
562. s are enabled by the flag XBangPatterns 7 19 1 Informal description of bang patterns The main idea is to add a single new production to the syntax of patterns pat pat Matching an expression e against a pattern p is done by first evaluating e to WHNF and then matching the result against p Example f1 x True This definition makes f1 is strict in x whereas without the bang it would be lazy Bang patterns can be nested of course E2 se y el Here f2 is strict in x but not in y A bang only really has an effect if it precedes a variable or wild card pattern 3 x y x y fa x y x y Here 3 and f4 are identical putting a bang before a pattern that forces evaluation anyway does nothing There is one apparent exception to this general rule that a bang only makes a difference when it precedes a variable or wild card a bang at the top level of a let or where binding makes the binding strict regardless of the pattern We say apparent exception because the Right Way to think of it is that the bang at the top of a binding is not part of the pattern rather it is part of the syntax of the binding creating a bang pattern binding For example let x y e in b is a bang pattern binding Operationally it behaves just like a case expression Case e of x y gt b Like a case expression a bang pattern binding must be non recursive and is monomorphic However nested bangs in a pattern binding b
563. s been idle no Haskell computation has been running for a period of time The amount of idle time which must pass before a GC is performed is set by the I seconds option Specifying I0 disables the idle GC For an interactive application it is probably a good idea to use the idle GC because this will allow finalizers to run and deadlocked threads to be detected in the idle time when no Haskell computation is happening Also it will mean that a GC is less likely to happen when the application is busy and so responsiveness may be improved However if the amount of live data in the heap is particularly large then the idle GC can cause a significant delay and too small an interval could adversely affect interactive responsiveness This is an experimental feature please let us know if it causes problems and or could benefit from further tuning kisize Default 1k Set the initial stack size for new threads Note this flag used to be simply k but was renamed to ki in GHC 7 2 1 The old name is still accepted for backwards compatibility but that may be removed in a future version Thread stacks including the main thread s stack live on the heap As the stack grows new stack chunks are added as required if the stack shrinks again these extra stack chunks are reclaimed by the garbage collector The default initial stack size is deliberately small in order to keep the time and space overhead for thread creation to a minimum and to
564. s defined in the paper Derivable type classes Ralf Hinze and Simon Peyton Jones Haskell Workshop Montreal Sept 2000 pp94 105 These have been removed and replaced by the more general support for generic programming 7 26 Generic programming Using a combination of XDeriveGeneric Section 7 5 4 XDefaultSignatures Section 7 6 1 4 and XDeriv eAnyClass Section 7 5 6 you can easily do datatype generic programming using the GHC Generics framework This section gives a very brief overview of how to do it Generic programming support in GHC allows defining classes with methods that do not need a user specification when instanti ating the method body is automatically derived by GHC This is similar to what happens for standard classes such as Read and Show for instance but now for user defined classes 7 26 1 Deriving representations The first thing we need is generic representations The GHC Generics module defines a couple of primitive types that are used to represent Haskell datatypes gt Unit used for constructors without arguments data Ul p Ul Constants additional parameters and recursion of kind newtype Kl icp Kl unkl c gt eta information constructor names etc newtype Ml ic fp Mif unMl p Sums encode choice between constructors dardo 3 Sank dE te jo il Ge jp Ri ey jo Products encode multiple arguments to constructors abiguesioxie 6 Bese cava 6x2 E
565. s imported from other modules e Use ddump simpl stats to see what rules are being fired If you add dppr debug you get a more detailed listing e Use ddump rule firings or ddump rule rewrites to see in great detail what rules are being fired If you add dppr debug you get a still more detailed listing e The definition of say build in GHC Base 1hs looks like this build gk A a Corali Tos a gt lo lo gt lo gt Io el INLINE build build g g Notice the INLINE That prevents from being inlined when compiling PrelBase so that an importing module will see the and can match it on the LHS of a rule INLINE prevents any inlining happening in the RHS of the INLINE thing I regret the delicacy of this T e Inlibraries base GHC Base lhs look at the rules for map to see how to write rules that will do fusion and yet give an efficient program even if fusion doesn t happen More rules in GHC List 1lhs The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 273 327 7 24 Special built in functions GHC has a few built in functions with special behaviour In particular e inline allows control over inlining on a per call site basis e lazy restrains the strictness analyser e oneShot gives a hint to the compiler about how often a function is being called 7 25 Generic classes GHC used to have an implementation of generic classes a
566. s not an application in wrong2 the LHS has a pattern variable in the head A rule does not need to be in the same module as any of the variables it mentions though of course they need to be in scope All rules are implicitly exported from the module and are therefore in force in any module that imports the module that defined the rule directly or indirectly That is if A imports B which imports C then C s rules are in force when compiling A The situation is very similar to that for instance declarations Inside a RULE forall is treated as a keyword regardless of any other flag settings Furthermore inside a RULE the language extension XScopedTypeVariables is automatically enabled see Section 7 13 8 Like other pragmas RULE pragmas are always checked for scope errors and are typechecked Typechecking means that the LHS and RHS of a rule are typechecked and must have the same type However rules are only enabled if the fenable rewrite rules flag is on see Section 7 23 2 7 23 2 Semantics From a semantic point of view Rules are enabled that is used during optimisation by the fenable rewrite rules flag This flag is implied by O and may be switched off as usual by fno enable rewrite rules NB enabling fenable rewrit rules without O may not do what you expect though because without O GHC ignores all optimisation information in interface files see fignore interface pragmas Section 4 10 2 Note that
567. s on the stack were paired to the right of the environment in a single argument but now the environment and stack are separate arguments 7 18 6 Portability Although only GHC implements arrow notation directly there is also a preprocessor available from the arrows web page that translates arrow notation into Haskell 98 for use with other Haskell systems You would still want to check arrow programs with GHC tracing type errors in the preprocessor output is not easy Modules intended for both GHC and the preprocessor must observe some additional restrictions e The module must import Cont rol Arrow e The preprocessor cannot cope with other Haskell extensions These would have to go in separate modules e Because the preprocessor targets Haskell rather than Core 1et bound variables are monomorphic The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 256 327 7 19 Bang patterns GHC supports an extension of pattern matching called bang patterns written pat Bang patterns are under consideration for Haskell Prime The Haskell prime feature description contains more discussion and examples than the material below The key change is the addition of a new rule to the semantics of pattern matching in the Haskell 98 report Add new bullet 10 saying Matching the pattern pat against a value v behaves as follows e if y is bottom the match diverges e otherwise pat is matched against v Bang pattern
568. s the N RTS option to be used which allows threads to run in parallel on a multiprocessor or multicore machine See Section 4 15 e If a thread makes a foreign call and the call is not marked unsafe then other Haskell threads in the program will continue to run while the foreign call is in progress Additionally foreign exported Haskell functions may be called from multiple OS threads simultaneously See Section 8 2 4 eventlog Link the program with the eventlog version of the runtime system A program linked in this way can generate a runtime trace of events such as thread start stop to a binary file program event log which can then be interpreted later by various tools See Section 4 17 6 for more information event log can be used with threaded It is implied by debug rtsopts This option affects the processing of RTS control options given either on the command line or via the GHCRTS environment variable There are three possibilities rtsopts none Disable all processing of RTS options If RTS appears anywhere on the command line then the program will abort with an error message If the GHCRTS environment variable is set then the program will emit a warning message GHCRTS will be ignored and the program will run as normal rtsopts some this is the default setting Enable only the safe RTS options Currently only and info Any other RTS options on the command line or in the GHCRTS environment variable causes th
569. s the install package P to be both exposed and distrusted by GHC This command functions in the in a very similar way to the package command but in addition sets the selected packaged to be distrusted by GHC regardless of the contents of the package database see Section 7 29 distrust all Ignore the trusted flag on installed packages and distrust them by default If you use this flag and Safe Haskell then any packages you require to be trusted including base need to be explicitly trusted using trust options This option does not change the exposed hidden status of a package so it isn t equivalent to applying distr ust to all packages on the system see Section 7 29 4 9 2 The main package Every complete Haskell program must define main in module Main in package main Omitting the this package key flag compiles code for package main Failure to do so leads to a somewhat obscure link time error of the form usr bin ld Undefined symbols _ZCMain_main_closure The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 69 327 4 9 3 Consequences of packages for the Haskell language It is possible that by using packages you might end up with a program that contains two modules with the same name perhaps you used a package P that has a hidden module M and there is also a module M in your program Or perhaps the dependencies of packages that you used contain some overlapping modules Perhaps the program even
570. s the time between creation and the first use of the object e the use stage which lasts from the first use until the last use of the object and e The drag stage which lasts from the final use until the last reference to the object is dropped e An object which is never used is said to be in the void state for its whole lifetime A biographical heap profile displays the portion of the live heap in each of the four states listed above Usually the most interesting states are the void and drag states live heap in these states is more likely to be wasted space than heap in the lag or use states It is also possible to break down the heap in one or more of these states by a different criteria by restricting a profile by biography For example to show the portion of the heap in the drag or void state by producer PROG Rom hice no digagy Osho Once you know the producer or the type of the heap in the drag or void states the next step is usually to find the retainer s DOG TRUS Sle ECCE os NOTE this two stage process is required because GHC cannot currently profile using both biographical and retainer information simultaneously The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 140 327 5 4 4 Actual memory residency How does the heap residency reported by the heap profiler relate to the actual memory residency of your program when you run it You might see a large discrepancy between the residency repor
571. scarding them typically this is used when they are uninformative e g reflexive equations For wanted constraints the evidence will form part of the Core term that is generated after typechecking and can be checked by dcore lint It is possible for the plugin to create equality axioms for use in evidence terms but GHC does not check their consistency and inconsistent axiom sets may lead to segfaults or other runtime misbehaviour The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 303 327 Chapter 10 What to do when something goes wrong If you still have a problem after consulting this section then you may have found a bug please report it See Section 1 3 for details on how to report a bug and a list of things we d like to know about your bug If in doubt send a report we love mail from irate users Section 13 1 which describes Glasgow Haskell s shortcomings vs the Haskell language definition may also be of interest 10 1 When the compiler does the wrong thing Help The compiler crashed or panic d These events are always bugs in the GHC system please report them This is a terrible error message If you think that GHC could have produced a better error message please report it as a bug What about this warning from the C compiler For example warning Foo declared static but never defined Un sightly but shouldn t be a problem Se
572. se in expressions at the prompt when the module is interpreted see Section 2 4 5 For this reason you might sometimes want to force GHCi to load a module using the interpreter This can be done by prefixing a to the module name or filename when using load for example Prelude gt load A Compiling A A hs interpreted A gt When the is used GHCi ignores any pre compiled object code and interprets the module If you have already loaded a number of modules as object code and decide that you wanted to interpret one of them instead of re loading the whole set you can use add xM to specify that you want M to be interpreted note that this might cause other modules to be interpreted too because compiled modules cannot depend on interpreted ones To always compile everything to object code and never use the interpreter use the fobject code option see Section 2 10 HINT since GHCi will only use a compiled object file if it can be sure that the compiled version is up to date a good technique when working on a large program is to occasionally run ghc make to compile the whole project say before you go for lunch then continue working in the interpreter As you modify code the changed modules will be interpreted but the rest of the project will remain compiled 2 4 Interactive evaluation at the prompt When you type an expression at the prompt GHCi immediately evaluates and prints the result Prelude gt reverse hel
573. se the P RTS option to get the following additional information ticks The raw number of time ticks which were attributed to this cost centre from this we get the t ime figure mentioned above bytes Number of bytes allocated in the heap while in this cost centre again this is the raw number from which we get the alloc figure mentioned above What about recursive functions and mutually recursive groups of functions Where are the costs attributed Well although GHC does keep information about which groups of functions called each other recursively this information isn t displayed in the basic time and allocation profile instead the call graph is flattened into a tree as follows a call to a function that occurs elsewhere on the current stack does not push another entry on the stack instead the costs for this call are aggregated into the caller 5 1 1 Inserting cost centres by hand Cost centres are just program annotations When you say fprof auto to the compiler it automatically inserts a cost centre annotation around every binding not marked INLINE in your program but you are entirely free to add cost centre annotations yourself The syntax of a cost centre annotation is SCC name lt expression gt where name is an arbitrary string that will become the name of your cost centre as it appears in the profiling output and lt expression gt is any Haskell expression An SCC annotation extends as far to the ri
574. skell Compilation System User s Guide Version 7 10 2 109 327 Flag Description Static Dynamic Reverse vn set verbosity level dynamic fprint licit int licit 11 ae OA REO eg rS dynamic fno print explicit foralls foralls quantification in types fprint licit int explicit kind forall POER l an es Lak ROS dynamic fno print explicit kinds kinds and kind arguments in types errors output full span in error dape g messages Set the minimum heap size i Hsize dynamic to size Summarise timing stats for Rghc timing GHC same as RTS dynamic tstderr 4 19 2 Alternative modes of operation More details in Section 4 5 Flag Description Static Dynamic Reverse help Disply help mode Interactive mode normally interactive used by just running ghci mode see Chapter 2 for details Build a multi module Haskell program automatically figuring out make dependencies Likely to be mode much easier and faster than using make see Section 4 5 1 for details E Evaluate expr see mode eee Section 4 5 2 for details apenas Display the contents of an A g interface file Generate dependency information suitable for use M mode ina Makefile see Section 4 7 12 for details supported extensions display the supported ade supported language extensions languages show options display the supperted mode command line
575. sna Dump occurrence analysis dynamit S output D th ddump opt cmm ump E Ta ecm dynamic C optimising passes ddump parsed Dump parse tree dynamic ddump prep Dump prepared core dynamic ddump rn Dump renamer output dynamic ddump rule ae firings Dump rule firing info dynamic dd rule D detailed rule firi i ump rule Dump detailed rule firing die g rewrites info ddump rules Dump rules dynamic ddiip v t Dump vectoriser input and dyuamie output msi Dump final simplifier da e output ddump simpl Dump output from each dynie _ iterations simplifier iteration ddump spec Dump specialiser output dynamic Dump TH spliced ddump splices expressions and what they dynamic evaluate to ddump stg Dump final STG dynamic dp serna Dump strictness analyser diaii g output ddump strsigs Dump strictness signatures dynamic The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 130 327 Flag Description Static Dynamic Reverse ddump tc Dump typechecker output dynamic Show evaluated TH y h fil d 7 acta lcs declarations in a th hs file SEO ddump types Dump type signatures dynamic k D ker i ddump worker ump worker wrapper dynamic 7 wrapper output ddump if trac Trace interface files dynamic ddump tc trac Trace typ
576. sors simultaneously Concurrency on the other hand is a means of abstraction it is a convenient way to structure a program that must respond to multiple asynchronous events However the two terms are certainly related By making use of multiple CPUs it is possible to run concurrent threads in parallel and this is exactly what GHC s SMP parallelism support does But it is also possible to obtain performance improvements with parallelism on programs that do not use concurrency This section describes how to use GHC to compile and run parallel programs in Section 7 28 we describe the language features that affect parallelism 4 15 1 Compile time options for SMP parallelism In order to make use of multiple CPUs your program must be linked with the threaded option see Section 4 12 6 Addi tionally the following compiler options affect parallelism feager blackholing Blackholing is the act of marking a thunk lazy computuation as being under evaluation It is useful for three reasons firstly it lets us detect certain kinds of infinite loop the NonTermination exception secondly it avoids certain kinds of space leak and thirdly it avoids repeating a computation in a parallel program because we can tell when a computation is already in progress The option feager blackholing causes each thunk to be blackholed as soon as evaluation begins The default is lazy blackholing whereby thunks are only marked as being under evaluation when a
577. ssTarget test_main hs Nothing setTargets target load LoadAllTargets The argument to runGhc is a bit tricky GHC needs this to find its libraries so the argument must refer to the directory that is printed by ghc print 1ibdir for the same version of GHC that the program is being compiled with Above we therefore use the ghc paths package which provides this for us Compiling it results in S cat test_main hs Main putStrin hi ghc package ghc simple_ghc_api hs ico a Comos mae Menim simple_ghc_api hs simple_ghc_api o Linking simple _ghc_api S simple_ghc_api S test_main hi For more information on using the API as well as more samples and references please see this Haskell org wiki page The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 298 327 9 3 Compiler Plugins GHC has the ability to load compiler plugins at compile time The feature is similar to the one provided by GCC and allows users to write plugins that can adjust the behaviour of the constraint solver inspect and modify the compilation pipeline as well as transform and inspect GHC s intermediate language Core Plugins are suitable for experimental analysis or optimization and require no changes to GHC s source code to use Plugins cannot optimize inspect C nor can they implement things like parser front end modifications like GCC apart from limited changes to the constraint solver If you feel
578. ssion A pattern A type A top level declaration Only the first two are described in the paper e A quoter is a value of type Language Haskell TH Quote QuasiQuoter which is defined thus data QuasiQuoter QuasiQuoter quoteExp String gt O Exp cereales YS Siew gt Q Bar quoteType String gt Q Type quoteDec String gt Q Dec That is a quoter is a tuple of four parsers one for each of the contexts in which a quasi quote can occur e A quasi quote is expanded by applying the appropriate parser to the string enclosed by the Oxford brackets The context of the quasi quote expression pattern type declaration determines which of the parsers is called The example below shows quasi quotation in action The quoter expr is bound to a value of type QuasiQuoter defined in module Expr The example makes use of an antiquoted variable n indicated by the syntax int n this syntax for anti quotation was defined by the parser s author not by GHC This binds n to the integer value argument of the constructor Int Gl xpr when pattern matching Please see the referenced paper for further details regarding anti quotation as well as the description of a technique that uses SYB to leverage a single parser of type String gt a to generate both an expression parser that returns a value of type O Exp and a pattern parser that returns a value of type Q Pat Quasiquoters must obey the same stage restri
579. stack of package databases Additionally file will also be the database modified by a register unregister expose or hide command unless it is overridden by a later package db user or global option force Causes ghc pkg to ignore missing dependencies directories and libraries when registering a package and just go ahead and add it anyway This might be useful if your package installation system needs to add the package to GHC before building and installing the files The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 74 327 global Operate on the global package database this is the default This flag affects the register update unregi ster expose and hide commands help Outputs the command line syntax user Operate on the current user s local package database This flag affects the register update unregister expose and hide commands v n verbose n Control verbosity Verbosity levels range from 0 2 where the default is 1 and v alone selects level 2 V version Output the ghc pkg version number ipid Causes ghc pkg to interpret arguments as installed package IDs e g an identifier like unix 2 3 1 0 de780 3 1a8cd88d2161b29b083c94240 This is useful if providing just the package name and version are ambiguous in old versions of GHC this was guaranteed to be unique but this invariant no longer necessarily holds 4 9 8 Building a package from Haskell so
580. stead when binding a type variable you can simply mention a kind variable in a kind annotation for that type variable binding thus ATA im SR Te Se as el IMI Gan vey GHC now infers kind 1 Ss se meulil ik ke gt 2 gt k gt amp The kind forall is placed just outside the outermost type variable binding whose kind annotation mentions the kind variable For example ee Local a me mw e gt Ie LE A O SN s rosana task ulglie Ses 4 m Ge gt AC S A EA g3 O A ES mo i a c gt e gt ME 162 28 E O A AE OA Cagix UE 5 im E He LE Here in f1 there is no kind annotation mentioning the polymorphic kind variable so k is generalised at the top level of the signature for 1 making the signature for 1 is as polymorphic as possible But in the case of of 2 we give a kind annotation inthe forall a k binding and GHC therefore puts the kind foral 1 right there too Note These rules are a bit indirect and clumsy Perhaps GHC should allow explicit kind quantification But the implicit quantification e g in the declaration for data type T above is certainly very convenient and it is not clear what the syntax for explicit quantification should be 7 8 3 Polymorphic kind recursion and complete kind signatures Just as in type inference kind inference for recursive types can only use monomorphic recursion Consider this contrived example data Tm a MkT m a T Maybe m a GilC almir
581. ster P Remove the specified package from the database ghc pkg check Check consistency of dependencies in the package database and report packages that have missing depen dencies ghc pkg expose P Sets the exposed flag for package P to True ghc pkg hide P Sets the exposed flag for package P to False ghc pkg trust P Sets the trusted flag for package P to True ghc pkg distrust P Sets the trusted flag for package P to False ghc pkg list P simple output This option displays the currently installed packages for each of the databases known to ghc pkg That includes the global database the user s local database and any further files specified using the f option on the command line Hidden packages those for which the exposed flag is Fal se are shown in parentheses in the list of packages If an optional package identifier P is given then only packages matching that identifier are shown If the option simple output is given then the packages are listed on a single line separated by spaces and the database names are not included This is intended to make it easier to parse the output of ghc pkg list using a script ghc pkg find module M simple output This option lists registered packages exposing module M Examples ghc pkg find module Var c fptools validate ghc driver package conf inplace ghc 6 9 20080428 ghc pkg find module Data Sequence c fptools validate ghc driver package conf inplace containers 0 1
582. t in fact an MD5 hash of each interface file and of each declaration within the interface file It also keeps in every interface file a list of the fingerprints 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 recompilation checking is on GHC will be clever It compares the fingerprints on the things it needs this time with the fingerprints 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 early in the process saying Compilation IS NOT required What a beautiful sight You can read about how all this works in the GHC commentary 4 7 9 How to compile mutually recursive modules GHC supports the compilation of mutually recursive modules This section explains how Every cycle in the module import graph must be broken by a hs boot file Suppose that modules A hs and B hs are Haskell source files thus module A where oo Bh Bos newtype TA MkTA Int 2 RS AUR SAA f MkKTB x MkTA x module B where import SOURCE A TA data TB MkTB Int G 88 WA gt Ws g MkTA x MkTB x Here A imports B but B imports A with a SOURCE pragma which breaks the circular dependency Every loop in the module import graph must be broken by a SOURCE import
583. t Foo GHC always treats the last parameter of the instance Foo in this example as the type whose instance is being derived 7 5 3 Deriving instances of extra classes Data etc Haskell 98 allows the programmer to add deriving declaration for classes specified in the deriving clause In Haskell 98 the only classes that may appear in the deriving clause are the standard classes 1 Eq Ord Enum Ix Bou Eq Ord toa data type declaration to generate a standard instance nded Read and Show GHC extends this list with several more classes that may be automatically derived e With XDeriveGeneric you can derive instances of the classes Generic and Genericl defined in GHC Generics You can use these to define generic functions as described in Section 7 26 e With XDeriveFunctor you can derive instances of the class Functor defined in GHC Base e With XDeriveDataTypeable you can derive instances of the class Data defined in Data Data See Section 7 5 4 for deriving Typeable e With XDeriveFoldable you can derive instances of the class Foldable defined in Data Foldable e With XDeriveTraversable you can derive instances of the class Traversable defined in Data Traversable Since the Traversable instance dictates the instances of Functor and Foldable you ll probably want to derive them too so XDeriveTraversabl implies XDeriveFunctor and XDeriveFoldable You can also use a stand
584. t ambiguity More generally we need only regard a type as ambiguous if it contains a variable on the left of the gt that 1s not uniquely determined either directly or indirectly by the variables on the right Dependencies also help to produce more accurate types for user defined functions and hence to provide earlier detection of errors and less cluttered types for programmers to work with Recall the previous definition for a function f YA AS AS Ss Sy for which we originally obtained a type to Cel bers a ds Collect sb e gt ac ME Ne reo a Given the dependency information that we have for Collects however we can deduce that a and b must be equal because they both appear as the second parameter in a Collects constraint with the same first parameter c Hence we can infer a shorter and more accurate type for f AS OMS SES RAE gt a gt a gt c gt c The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 198 327 In a similar way the earlier definition of g will now be flagged as a type error Although we have given only a few examples here it should be clear that the addition of dependency information can help to make multiple parameter classes more useful in practice avoiding ambiguity problems and allowing more general sets of instance declarations 7 6 3 Instance declarations An instance declaration has the form instance assertionl assertionn gt
585. t any number of generations Anything larger than about 4 is probably not a good idea unless your program runs for a long time because the oldest generation will hardly ever get collected Specifying 1 generation with RTS G1 gives you a simple 2 space collector as you would expect In a 2 space collector the A option see above specifies the minimum allocation area size since the allocation area will grow with the amount of live data in the heap In a multi generational collector the allocation area is a fixed size unless you use the H option see below The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 99 327 qg gen New in GHC 6 12 1 Default 0 Use parallel GC in generation gen and higher Omitting gen turns off the parallel GC completely reverting to sequential GC The default parallel GC settings are usually suitable for parallel programs i e those using par Strategies or with multiple threads However it is sometimes beneficial to enable the parallel GC for a single threaded sequential program too especially if the program has a large amount of heap data and GC is a significant fraction of runtime To use the parallel GC in a sequential program enable the parallel runtime with a suitable N option and additionally it might be beneficial to restrict parallel GC to the old generation with qg1 qb gen New in GHC 6 12 1 Default 1 Use load balancing in the parallel GC in generation
586. t mechanism for extracting parallelism from pure code is to use the par combinator which is closely related to and often used with seq Both of these are available from the parallel library iiano O Spez imss l Musee pagr 8 gt lo gt la peesi sg a OO The expression x par y sparks the evaluation of x to weak head normal form and returns y Sparks are queued for execution in FIFO order but are not executed immediately If the runtime detects that there is an idle CPU then it may convert a spark into a real thread and run the new thread on the idle CPU In this way the available parallelism is spread amongst the real CPUs For example consider the following parallel version of our old nemesis nfib import Control Parallel rado 28 Mate gt aye meo m ia lt il al otherwise par nl pseg n2 nl n2 1 where nl nfib n 1 D2 medo MZ For values of n greater than 1 we use par to spark a thread to evaluate nfib n 1 and then we use pseq to force the parent thread to evaluate nfib n 2 before going on to add together these two subexpressions In this divide and conquer approach we only spark a new thread for one branch of the computation leaving the parent to evaluate the other branch Also we must use pseq to ensure that the parent will evaluate n2 before n1 in the expression n1 n2 1 Itis not sufficient to reorder the expression as n2 n1 1 because the compiler may not generate code to
587. t to do now is to define a front end class which is exposed to the user class Serialize a wher purt gs ESE default put Generic a GSerializ Rep a gt a gt Bit joule Gjov o O Here we use a default signature to specify that the user does not have to provide an implementation for put as long as there is a Generic instance for the type to instantiate For the UserTree type for instance the user can just write instanc Serialize a gt Serializ UserTr a The default method for put is then used corresponding to the generic implementation of serialization If you are using XDeriveAnyClass the same instance is generated by simply attaching a deriving Serialize clause to the UserTree datatype declaration For more examples of generic functions please refer to the generic deriving package on Hackage 7 26 4 More information For more details please refer to the Haskell Wiki page or the original paper e Jose Pedro Magalhaes Atze Dijkstra Johan Jeuring and Andres Loeh A generic deriving mechanism for Haskell Proceed ings of the third ACM Haskell symposium on Haskell Haskell 2010 pp 37 48 ACM 2010 7 27 Roles Using XGeneralizedNewtypeDeriving Section 7 5 5 1 a programmer can take existing instances of classes and lift these into instances of that class for a newtype However this is not always safe For example consider the following newtype Age MkAge unAge Int typ
588. t you either need to escape or convert to so you should be fine just using those everywhere If you need to use tools that do some kind of path mangling that depends on unix style paths one fun example is trying to interpret as a separator in path lists you can still try to convert paths using cygpath just before they are passed to GHC and friends If you don t have cygpath you probably don t have cygwin and hence no problems with it unless you want to write one build process for several platforms Again relative paths are your friend but if you have to use absolute paths and don t want to use different tools on different platforms you can simply write a short Haskell program to print the current directory thanks to George Russell for this idea compiled with GHC this will give you the view of the file system that GHC depends on which will differ depending on whether GHC is compiled with cygwin s gcc or mingw s gcc or on a real unix system that little The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 311 327 program can also deal with escaping V in paths Apart from the banner and the startup time something like this would also do amp echo YDirectory Sia a Directory gt jolie Sie bli a imig o CaLL o shew gner 12 6 Building and using Win32 DLLs On Win32 platforms the compiler is capable of both producing and using dynamic link libraries DLL
589. ted by a command consists of values for the free local variables in the command plus a stack of anonymous values In all the prior examples we made no assumptions about this stack In the second argument to handleA the value of the exception has been added to the stack input to the handler The command form of lambda merely gives this value a name More concretely the input to a command consists of a pair of an environment and a stack Each value on the stack is paired with the remainder of the stack with an empty stack being So operators like handleA that pass extra inputs to their subcommands can be designed for use with the notation by placing the values on the stack paired with the environment in this way More precisely the type of each argument of the operator and its result should have the form The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 255 327 AM Gele aae E where e is a polymorphic variable representing the environment and ti are the types of the values on the stack with t1 being the top The polymorphic variable e must not occur in a ti or t However the arrows involved need not be the same Here are some more examples of suitable operators Bracket 38 oon gt e es la gt a 6 0 8 e gt a e e e e gt a ers el runReader gt a e s c gt a e State s c runState it gt a le s c gt a e State s c State We can
590. ted by the heap profiler and the residency reported by tools on your system eg ps or top on Unix or the Task Manager on Windows There are several reasons for this There is an overhead of profiling itself which is subtracted from the residency figures by the profiler This overhead goes away when compiling without profiling support of course The space overhead is currently 2 extra words per heap object which probably results in about a 30 overhead Garbage collection requires more memory than the actual residency The factor depends on the kind of garbage collection algorithm in use a major GC in the standard generation copying collector will usually require 3L bytes of memory where L is the amount of live data This is because by default see the RTS F option we allow the old generation to grow to twice its size 2L before collecting it and we require additionally L bytes to copy the live data into When using compacting collection see the RTS c option this is reduced to 2L and can further be reduced by tweaking the F option Also add the size of the allocation area currently a fixed 512Kb The stack isn t counted in the heap profile by default See the RTS xt option The program text itself the C stack any non heap data eg data allocated by foreign libraries and data allocated by the RTS and mmap d memory are not counted in the heap profile 5 5 hp2ps heap profile to PostScript Usage hp2ps flags
591. ter and equality constraints e Tuples all of whose component types have kind Constraint So for example the type Show a Ord a is of kind Constraint e Anything whose form is not yet known but the user has declared to have kind Constraint for which they need to im port it from GHC Exts So for example type Foo f gt Constraint forall b f b gt b gt bis allowed as well as examples involving type families ue Ecmully IS E la 33 CONSE Canne type instance Typ Int b Show b type instance Typ Bool b Num b ue 28 Mya a le gt a 19 gt lo func Note that because constraints are just handled as types of a particular kind this extension allows type constraint synonyms The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 225 327 type Stringy a Read a Show a LOO g3 Sririney a gt a gt Sroine SCTE gt A foo x show x read Presently only standard constraints tuples and type synonyms for those two sorts of constraint are permitted in instance contexts and superclasses without extra flags The reason is that permitting more general constraints can cause type checking to loop as 1t would with these two programs type family Clsish ua type instance Clsish a Cls a class Clsish a gt Cls a where class OkCls a where type family OkClsish ua type instance OkClsish a OkCls a instance OkClsish a gt OkCls a where You may write programs th
592. ter location information in runtime errors e g from error and partial functions like head For more details see Section 7 13 4 5 A bug in the typechecker which could result in strange inconsistent reduction of type families has been fixed issue 10488 A variety of fixes of the new API annotations support A bug which caused GHC to generate bad DWARF unwinding information has been fixed issue 10236 DWARF support should now work on Windows MinGW 10468 A bug which caused GHC s 1ibffi so library to be built with executable stacks on some platforms has been fixed issue 10208 A bus error on SPARC machines caused by misaligned data accesses in the RTS has been fixed A bug which caused the simplifier to produce code which segfaulted at runtime has been fixed issue 10538 A type system bug which could allow a user to write unsafeCoerce has been fixed issue 9858 A bug which caused GHC to generate incorrect hyperlinks to documentation in Haddock has been fixed 10206 A bug in the typechecker which allowed erroneous programs using Coercible to typecheck has been fixed issue 10285 An issue which could cause the Call Arity analysis to perform poorly in general has been fixed issue 10293 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 10 327 Several dozen bugs in the new API annotations work have been fixed issues 10395 10363 10358 10357 10315 10314 10312 and many
593. text to stdout For example ghc show iface M hi The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 47 327 ghc supported extensions ghc supported languages Print the supported language extensions ghc show options Print the supported command line options This flag can be used for autocompletion in a shell ghc info Print information about the compiler ghc versionghc V Print a one line string including GHC s version number ghc numeric version Print GHC s numeric version number only ghc print libdir Print the path to GHC s library directory This is the top of the directory tree containing GHC s libraries interfaces and include files usually something like usr local lib ghc 5 04 on Unix This is the value of 1ibdir in the package configuration file see Section 4 9 4 5 1 Using ghc make In this mode GHC will build a multi module Haskell program by following dependencies from one or more root modules usually just Main For example if your Main module is in a file called Main hs you could compile and link the program like this ghe make Main hs In fact GHC enters make mode automatically if there are any Haskell source files on the command line and no other mode is specified so in this case we could just type ghc Main hs Any number of source file names or module names may be specified GHC will figure out all the modules in the program by following the im
594. th certain names e g names containing install setup or patch Without the manifest file to turn off installer detection attempting to run an executable that Windows deems to be an installer will return a permission error code to the invoker Depending on the invoker the result might be a dialog box asking the user for elevated permissions or it might simply be a permission denied error Installer detection can be also turned off globally for the system using the security control panel but GHC by default generates binaries that don t depend on the user having disabled installer detection The fno gen manifest disables generation of the manifest file One reason to do this would be if you had a manifest file of your own for example In the future GHC might use the manifest file for more things such as supplying the location of dependent DLLs fno gen manifest also implies fno embed mani fest see below The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 91 327 fno embed manifest The manifest file that GHC generates when linking a binary on Windows is also embedded in the executable itself by default This means that the binary can be distributed without having to supply the manifest file too The embedding is done by running windres to see exactly what GHC does to embed the manifest use the v flag A GHC installation comes with its own copy of windres for this reason See also pg
595. that each universally quantified type variable tvi must be reachable from t ype and b that every constraint ci mentions at least one of the universally quantified type variables tvi These ad hoc restrictions are completely subsumed by the new ambiguity check End of historical note 7 13 4 Implicit parameters Implicit parameters are implemented as described in Implicit parameters dynamic scoping with static types J Lewis MB Shields E Meijer J Launchbury 27th ACM Symposium on Principles of Programming Languages POPL 00 Boston Jan 2000 Most of the following still rather incomplete documentation is due to Jeff Lewis Implicit parameter support is enabled with the option XImplicitParams A variable is called dynamically bound when it is bound by the calling context of a function and statically bound when bound by the callee s context In Haskell all variables are statically bound Dynamic binding of variables is a notion that goes back to Lisp but was later discarded in more modern incarnations such as Scheme Dynamic binding can be very confusing in an untyped language and unfortunately typed languages in particular Hindley Milner typed languages like Haskell only support static scoping of variables However by a simple extension to the type class system of Haskell we can support dynamic binding Basically we express the use of a dynamically bound variable as a constraint on the type These constraints lead to types o
596. the arity determined by the kind of the family A data family instance declaration can use the full expressiveness of ordinary data or newt ype declarations e Although a data family is introduced with the keyword data a data family instance can use either data or newt ype For example data family T a Hy Iie S e ZE O OH TC Bool data instance newtype instance T Char e Adata instance can use GADT syntax for the data constructors and indeed can define a GADT For example data family Gab data instance G a b where EL 3 gt G imel be s3 E kal Bool e You can use a deriving clause on a data instance or newtype instance declaration Even if data families are defined as toplevel declarations functions that perform different computations for different family instances may still need to be defined as methods of type classes In particular the following is not possible data family T a data instance T Int A data instance T Char B DOO 288 I E gt Alone o Al WRONG These two equations together LOOM B 2 Sa poo WA oro tds El TS Sacra The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 209 327 Instead you would have to write foo as a class operation thus class Foo a where EOS 9 Da gt de instance Foo Int where foo A 1 instance Foo Char where foo B 2 Given the functionality provided by GADTs Generalised Algebraic Data Types it might seem as
597. the author of Danger a very large attack surface essentially any package currently installed on the system Should any of these packages have a vulnerability then the Danger module can exploit this The only way to stop this would be to patch or remove packages with known vulnerabilities even if they should only be used by trusted code such as the RIO module The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 282 327 To stop these attacks Safe Haskell can be used This is done by compiling the RIO module with the XTrustworthy flag and compiling the Danger module with the XSafe flag The use of the XSafe flag to compile the Danger module restricts the features of Haskell that can be used to a safe subset This includes disallowing unsafePerforml0 Template Haskell pure FFI functions RULES and restricting the operation of Overlapping Instances The XSafe flag also restricts the modules can be imported by Danger to only those that are considered trusted Trusted modules are those compiled with XSafe where GHC provides a mechanical guarantee that the code is safe Or those modules compiled with XTrustworthy where the module author claims that the module is Safe This is why the RIO module is compiled with XTrustworthy to allow the Danger module to import it The XTrustwo rthy flag doesn t place any restrictions on the module like XSafe does Instead the module author claims that while code may use unsafe f
598. the following Haskell source code which we place in a file Main hs The i stands for Interactive 2 except foreign export at the moment The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 13 327 main print fac 20 ras Q i fac n a Lac n 1 You can save Main hs anywhere you like but if you save it somewhere other than the current directory then we will need to change to the right directory in GHCi Preduder ac a where dir is the directory or folder in which you saved Main hs To load a Haskell source file into GHC1 use the load command Prelude gt load Main Compiling Main Main hs interpreted Ok modules loaded Main Main gt GHCi has loaded the Main module and the prompt has changed to Main gt to indicate that the current context for expressions typed at the prompt is the Main module we just loaded we ll explain what the means later in Section 2 4 5 So we can now type expressions involving the functions from Main hs Main gt fac 17 355687428096000 Loading a multi module program is just as straightforward just give the name of the topmost module to the load command hint load can be abbreviated to 1 The topmost module will normally be Main but it doesn t have to be GHCi will discover which modules are required directly or indirectly by the topmost module and load them all in dependency order 2 2 1 Modules vs fi
599. the graph in detail but it is unsuitable for inclusion in LaTeX documents The e option causes the graph to be drawn in portrait mode with float specifying the width in inches millimetres or points the default The resulting PostScript file conforms to the Encapsulated PostScript EPS convention and it can be included in a LaTeX document using Rokicki s dvi to PostScript converter dvips g Create output suitable for the gs PostScript previewer or similar In this case the graph is printed in portrait mode without scaling The output is unsuitable for a laser printer 1 Normally a profile is limited to 20 bands with additional identifiers being grouped into an OTHER band The 1 flag removes this 20 band and limit producing as many bands as necessary No key is produced as it won t fit It is useful for creation time profiles with many bands The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 141 327 m lt int gt Normally a profile is limited to 20 bands with additional identifiers being grouped into an OTH specifies an alternative band limit the maximum is 20 ER band The m flag m0 requests the band limit to be removed As many bands as necessary are produced However no key is produced as it won t fit It is useful for displaying creation time profiles with many bands p Use previous parameters By default the PostScript graph is automatically scaled both horizont
600. the program is ambiguous show reverse which is what GHCi computes here has type Show a gt String and how that displays depends on the type a For example ghci gt reverse String we goei reverse TI 28 tal However it is tiresome for the user to have to specify the type so GHCi extends Haskell s type defaulting rules Section 4 3 4 of the Haskell 2010 Report as follows The standard rules take each group of constraints Cl a C2 a Cn a for each type variable a and defaults the type variable if The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 23 327 1 The type variable a appears in no other constraints 2 All the classes Ci are standard 3 At least one of the classes Ci is numeric At the GHCi prompt or with GHC if the XExtendedDefaultRules flag is given the following additional differences apply e Rule 2 above is relaxed thus All of the classes Ci are single parameter type classes e Rule 3 above is relaxed this At least one of the classes Ci is numeric or is Show Eq or Ord e The unit type is added to the start of the standard list of types which are tried when doing type defaulting The last point means that for example this program ena EE TO main print def instance Num def Num a Enum a gt a def toEnum 0 prints rather than 0 as the type is defaulted to rather than Integer The motivation for the
601. then it is parsed as a Haskell String otherwise it is treated as a literal string set prompt2 prompt Sets the string to be used as the continuation prompt used when using the command in GHCi set stop num cmd Set a command to be executed when a breakpoint is hit or a new item in the history is selected The most common use of set stop is to display the source code at the current location e g set stop list If a number is given before the command then the commands are run when the specified breakpoint only is hit This can be quite useful for example set stop 1 continue effectively disables breakpoint 1 by running continue whenever it is hit although GHCi will still emit a message to say the breakpoint was hit What s more with cunning use of def and cmd you can use set stop to implement conditional breakpoints Main gt def cond expr gt return cmd if expr then return else reruza peo inua UL Main gt sel stop 0 second e lt 3 Ignoring breakpoints for a specified number of iterations is also possible using similar techniques seti option Like set but options set with set i affect only expressions and commands typed at the prompt and not modules loaded with load in contrast options set with set apply everywhere See Section 2 8 3 Without any arguments displays the current set of options that are applied to expressions and commands typed at the prompt show
602. then the pragma SPECIALIZE f lt type gt is valid if and only if the definition f_spec lt type gt f_spec f is valid Here are some examples where we only give the type signature for the original function not its code i go he a 2 S 1p gt 15 SPECIALISE f Int gt b gt b Se ie ay Is lo gt a gt lo gt Io ASPE S TAM TSE gt s iore j lt 28 he a gt a gt a gt a SPECIALISE h Eq a gt a gt a gt a The last of these examples will generate a RULE with a somewhat complex left hand side try it yourself so it might not fire very well If you use this kind of specialisation let us know how well it works 7 22 9 1 SPECIALIZE INLINE A SPECIALIZE pragma can optionally be followed with a INLINE or NOINLINE pragma optionally followed by a phase as described in Section 7 22 6 The INLINE pragma affects the specialised version of the function only and applies even if the function is recursive The motivating example is this A GADT for arrays with type indexed representation data Arr e where ocio BR liac gt teca gt Arr mt ArrPair Int gt Arr el gt Arr e2 gt Arr el e2 le Se Aer e gt al gt 6 SPECIALISE INLINE Arr Int gt Int gt Int ESPE CATS EEN EEN IE A S Jo s2
603. ther the code will be used in a shared library or will use shared library versions of other packages it depends on There is additional complexity when installing and distributing shared libraries or programs that use shared libraries to ensure that all shared libraries that are required at runtime are present in suitable locations 4 13 1 Building programs that use shared libraries To build a simple program and have it use shared libraries for the runtime system and the base libraries use the dynamic flag ghae make dynamic Main hs This has two effects The first is to compile the code in such a way that it can be linked against shared library versions of Haskell packages such as base The second is when linking to link against the shared versions of the packages libraries rather than the static versions Obviously this requires that the packages were built with shared libraries On supported platforms GHC comes with shared libraries for all the core packages but if you install extra packages e g with Cabal then they would also have to be built with shared libraries nable shared for Cabal The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 92 327 4 13 2 Shared libraries for Haskell packages You can build Haskell code into a shared library and make a package to be used by other Haskell programs The easiest way is using Cabal simply configure the Cabal package with the nable shared flag
604. thread is paused for some reason Lazy blackholing is typically more efficient by 1 2 or so because most thunks don t need to be blackholed However eager blackholing can avoid more repeated computation in a parallel program and this often turns out to be important for parallelism We recommend compiling any code that is intended to be run in parallel with the feager blackholing flag 4 15 2 RTS options for SMP parallelism There are two ways to run a program on multiple processors call Control Concurrent setNumCapabilities from your program or use the RTS N option N x Use x simultaneous threads when running the program The runtime manages a set of virtual processors which we call capabilities the number of which is determined by the N option Each capability can run one Haskell thread at a time so the number of capabilities is equal to the number of Haskell threads that can run physically in parallel A capability is animated by one or more OS threads the runtime manages a pool of OS threads for each capability so that if a Haskell thread makes a foreign call see Section 8 2 4 another OS thread can take over that capability Normally x should be chosen to match the number of CPU cores on the machine For example on a dual core machine we would probably use RTS N2 RTS Omitting x i e RTS N RTS lets the runtime choose the value of x itself based on how many processors are in your machine 3 Whether hy
605. tial check for an empty list we know that in the recursive case this pattern match is redundant As such fspec constr will transform the above code to last s al a Last El error last last x xs last x xs where last x DI x last oe 67 8 Ye last Y ye As well avoid unnecessary pattern matching it also helps avoid unnecessary allocation This applies when a argument is strict in the recursive call to itself but not on the initial entry As strict recursive branch of the function is created similar to the above example It is also possible for library writers to instruct GHC to perform call pattern specialisation extremely aggressively This is necessary for some highly optimized libraries where we may want to specialize regardless of the number of specialisations or the size of the code As an example consider a simplified use case from the vector library import GHC Types SPEC told 8 a gt ly gt a gt a gt Sereca lo gt A INLINE foldl Tolo ts Suc See Ss scokell logs SRC where tol dilo sBEC 4 is case step s Of Yaelle Se i gt role logg same E a z a Skip gt Folo logs SPIC m S Done gt m Here after GHC inlines the body of foldl to a call site it will perform call pattern specialization very aggressively on foldl_loop due to the use of SPEC in the argument of the loop body SPEC from GHC Types is specifically recognized by the co
606. tinabe 2 0 5 6 1 0 his lab artes SU 2 or lO extra libraries rt util dl extra ghci libraries taclude 0i239 tise lalo aneno a 12 i waa 2 3 i 0 acilvuels includes HsUnix h execvpe h depends base 4 2 0 0 247bb20cde37c3ef4093ee124e04bc1c The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 76 327 hugs options cc options ld options framework dirs frameworks haddock interfaces usr share doc ghc html libraries unix unix haddock haddock html usr share doc ghc html libraries unix Here is a brief description of the syntax of this file A package description consists of a number of field value pairs A field starts with the field name in the left hand column followed by a and the value continues until the next line that begins in the left hand column or the end of file The syntax of the value depends on the field The various field types are freeform Any arbitrary string no interpretation or parsing is done string A sequence of non space characters or a sequence of arbitrary characters surrounded by quotes string list A sequence of strings separated by commas The sequence may be empty In addition there are some fields with special syntax e g package names version dependencies The allowed fields with their types are name The package s name without the version id The installed package ID It is up to you to choose a suitable one v
607. tion Oddly enough people really do use this option Our pal in Durham England Paul Callaghan writes Some people here use it for a variety of purposes honestly e g confirmation that the code machine is doing something infinite loop detection gauging cost of recently added code Certain people can even tell what stage the program is in by the beep pattern But the major use is for annoying others in the same office Dx An RTS debugging flag only available if the program was linked with the debug option Various values of x are provided to enable debug messages and additional runtime sanity checks in different subsystems in the RTS for exam ple RTS Ds RTS enables debug messages from the scheduler Use RTS to find out which debug flags are supported Debug messages will be sent to the binary event log file instead of stdout if the 1 option is added This might be useful for reducing the overhead of debug tracing rfile Produce ticky ticky statistics at the end of the program run only available if the program was linked with debug The file business works just like on the S RTS option above For more information on ticky ticky profiling see Section 5 8 xc Only available when the program is compiled for profiling When an exception is raised in the program this option causes a stack trace to be dumped to stderr This can be particularly useful for debugging if your program is complaining abouta he
608. tion lets f project out some information from the elements of the list it is transforming An example is shown in the opening example where sortWith is supplied with a function that lets it find out the sum salary for any item in the list comprehension it transforms then group by e using f This is the most general of the grouping type statements In this form f is required to have type forall a a gt t gt a gt a As with the then f by e case above the first argument is a function supplied to f by the compiler which lets it compute e on every element of the list being transformed However unlike the non grouping case f additionally partitions the list into a number of sublists this means that at every point after this statement binders occurring before it in the comprehension refer to lists of possible values not single values To help understand this let s look at an example ls WO Salim cuclsy O Grotten ata RIC eS lote COGS e SOE Les out aleteo groupRuns Eq b gt a gt b gt la gt Ilall groupRuns f groupBy Ax y gt f x f y Guto as x 37 x lt flees sre IZA E 7 s 14556 then group by x using groupRuns This results in the variable out put taking on the value below 1 4 5 61 2 4 5 61 3 4 5 61 1 4 5 61 2 4 5 6 Note that we have used the the function to change the type of x from a list to its original numeric type
609. tion 7 22 Every language extension can also be turned into a command line flag by prefixing it with X for example XForeignFun ctionInterface Similarly all X flags can be written as LANGUAGE pragmas A list of all supported language extensions can be obtained by invoking gnc supported extensions see Section 4 5 Any extension from the Extension type defined in Language Haskell Extension may be used GHC will report an error if any of the requested extensions are not supported 7 22 2 OPTIONS GHC pragma The OPTIONS_GHC pragma is used to specify additional options that are given to the compiler when compiling this source file See Section 4 2 2 for details Previous versions of GHC accepted OPTIONS rather than OPTIONS_GHC but that is now deprecated OPTIONS_GHC is a file header pragma see Section 7 22 7 22 3 INCLUDE pragma The INCLUDE used to be necessary for specifying header files to be included when using the FFI and compiling via C It is no longer required for GHC but is accepted and ignored for compatibility with other compilers 7 22 4 WARNING and DEPRECATED pragmas The WARNING pragma allows you to attach an arbitrary warning to a particular function class or type A DEPRECATED pragma lets you specify that a particular function class or type is deprecated There are two ways of using these pragmas e You can work on an entire module thus module Wibble DEPRECATED Use Wobble inst
610. tionally these warnings can be silenced with the fno warn partial type signatures flag 7 15 1 Syntax A partial type signature has the following form forall a b C1 C2 gt tau It consists of three parts e The type variables a b e The constraints C1 C2 e The mono type tau We distinguish three kinds of wildcards 7 15 1 1 Type Wildcards Wildcards occurring within the monotype tau part of the type signature are type wildcards type is often omitted as this is the default kind of wildcard Type wildcards can be instantiated to any monotype like Bool or Maybe Bool including functions and higher kinded types like Int gt Bool or Maybe mor 29 loo gt not x not x amina BOOL gt BOOL maybools maybools Just True Inferred Maybe Bool Justel gs Wine Josti gwsg i Inferred Maybe Int cilccin 35 gt e mie filterInt filter las us merecidas a El gt el gt Jal arce Mame gt BOOL gt gt bae gt aw For instance the first wildcard in the type signature not would produce the following error message Test hs 4 17 Found hole _ with type Bool To use the inferred type enable PartialTypeSignatures a tas y SakCimercwuae woe Minos BOOL gt When a wildcard is not instantiated to a monotype it will be generalised over i e replaced by a fresh type variable of which the name will often start with w_ e g ROOS ey Sea
611. tively collectArgs Type gt Type collsctArcos APS A e ole E Ano sz collectArgs _ SIE 8 los gt BOO iia Agp Mae 1 Tiie SO False Matching on App directly is both hard to read and error prone to write And the situation is even worse when the matching is nested isimzimcla SE type gt BOGI terme mmdo Ago gt Aga aer lily A30 aer 111 Tris Terme Dno False Pattern synonyms permit abstracting from the representation to expose matchers that behave in a constructor like manner with respect to pattern matching We can create pattern synonyms for the known types we care about without committing the representation to them note that these don t have to be defined in the same module as the Type type pattern Arrow tl t2 App gt ict A pattern Int oa Mia Al pattern Maybe t App Maybe t Which enables us to rewrite our functions in a much cleaner style The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 160 327 collectArgs Type gt Type colMlSctAtegs MALENA e T eo eA rge collectArgs _ Simce ss Type gt Boal isInt Int True LS dde False SAME ovele BE os gt BOOI isIntEndo Arrow Int Int True SNE nOO False Note that in this example the pattern synonyms Int and Arrow can also be used as expressions they are bidirectional This 1s not necessarily the case unidirectional pattern synonyms can also be declared with
612. to C code hse2hs e 11 2 1 command line syntax 11 2 2 Inputsyntax 11 2 3 Custom constructs 11 2 4 Cross compilation 12 Running GHC on Win32 systems 12 1 Starting GHC on Windows platforms 12 2 Running GHCi on Windows 12 3 Interacting with the terminal 12 4 Differences in library behaviour 12 5 Using GHC and other GHC compiled executables withcygwin 2 2 o e e 12 5 1 Background 12 5 2 The problem 12 5 3 Thingstodo 12 6 Building and using Win32 DLLs 12 6 1 CreatingaDLL 12 6 2 Making DLLs to be called from other languages o o e 0000004 12 6 2 1 Using from VBA 12 6 2 2 Using from C 13 Known bugs and infelicities 13 1 Haskell standards vs Glasgow Haskell language non compliance 13 1 1 Divergence from Haskell 98 and Haskell 2010 o o e 13 1 1 1 Lexical syntax 13 1 1 2 Context free syntax 13 1 1 3 Expressions and patterns ee 13 1 1 4 Declarations and bindings 0 2 0 0 0 000000000000 13 1 1 5 Module system and interface files 2 0 o e e e 13 1 1 6 Numbers basic types and built in classes 2 1 o e e 13 1 1 7 In Prelude support 13 1 1 8 The Foreign Function Interface ee 13 1 2 GHC s
613. to get a boolean For example O OE DO f MkFoo val fn fn val What this allows us to do is to package heterogeneous values together with a bunch of functions that manipulate them and then treat that collection of packages in a uniform manner You can express quite a bit of object oriented like programming this way 7 4 6 1 Why existential What has this to do with existential quantification Simply that MkF oo has the nearly isomorphic type MRP oo Ss existe a lap a gt Bool gt Foo But Haskell programmers can safely think of the ordinary universally quantified type given above thereby avoiding adding a new existential quantification construct 7 4 6 2 Existentials and type classes An easy extension is to allow arbitrary contexts before the constructor For example data Baz forall a Eq a gt Bazl a a oralik s Sow 9 gt Baza o o gt o The two constructors have the types you d expect Bewil gg Torell a Ma a gt a gt a gt Baz Baz2 g8 orali lo Sinow lo S ly gt Ip gt 19 gt Baz But when pattern matching on Baz1 the matched values can be compared for equality and when pattern matching on Baz2 the first matched value can be converted to a string as well as applying the function to it So this program is legal The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 181 327 E 88 12 gt OTILE BAZA O A Yes otherwise No E Beazer
614. to the ArrowLoop class The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 253 327 7 18 2 Conditional commands In the previous example we used a conditional expression to construct the input for an arrow Sometimes we want to conditionally execute different commands as in PROCE gt alin He 3K AY then g lt x 1 else h lt y 2 which is translated to sucia Or E gt de E oe y tada beri ds elge Rice y gt gt gt chee Qs gt a gt e ll esse y gt sare gt gt gt la Since the translation uses the arrow concerned must belong to the ArrowChoice class There are also case commands like Case input of gt f lt x gt g lt x 1 IS O y h s l x2 NS AS returnA lt y ys The syntax is the same as for case expressions except that the bodies of the alternatives are commands rather than expressions The translation is similar to that of i f commands 7 18 3 Defining your own control structures As we re seen arrow notation provides constructs modelled on those for expressions for sequencing value recursion and conditionals But suitable combinators which you can define in ordinary Haskell may also be used to build new commands out of existing ones The basic idea is that a command defines an arrow from environments to values These environments assign values to the free local variables of the command Thus combinators that produce arrows
615. to use St ate parameters to serialize and thread state around This API is still considered experimental and will be prone to change The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 8 327 1 5 3 13 haskeline Version number 0 7 2 1 was 0 7 1 2 1 5 3 14 hoopl Version number 3 10 0 2 was 3 10 0 0 1 5 3 15 hpc Version number 0 6 0 2 was 0 6 0 1 The hpc command supports a new flag verbosity n which controls the verbosity level of subcommands mab 5 3 16 integer gmp Version number 1 0 0 0 was 0 5 1 0 The integer gmp package has been completely rewritten to be more efficient and interoperate more sanely with the GMP library Specifically GHC no longer needs to hook the GMP memory allocators to make allocations exist on the Haskell heap a complication which makes GMP dependent C libraries difficult This means external libraries that use GMP such as MPFR or FLINT can now be trivially FFI d to without any complication 1 5 3 17 pretty Version number 1 1 2 0 was 1 1 1 1 1 5 3 18 process Version number 1 2 3 0 was 1 2 0 0 1 5 3 19 template haskell Version number 2 10 0 0 was 2 9 0 0 1 5 3 20 terminfo Version number 0 4 0 1 was 0 4 0 0 1 5 3 21 time Version number 1 5 0 1 was 1 4 2 1 5 3 22 transformers Version number 0 4 2 0 was 0 3 0 0 1 5 3 23 unix Version number 2 7 1 0 was 2 7 0 0 The Glorious Glasgow Haskell Compilat
616. tor etags See ctags force identifier Prints the value of identifier in the same way as print Unlike print force evaluates each thunk that 1t encounters while traversing the value This may cause exceptions or infinite loops or further breakpoints which are ignored but displayed forward Move forward in the history See Section 2 5 5 See also trace history back help Displays a list of the available commands Repeat the previous command history num Display the history of evaluation steps With a number displays that many steps default 20 For use with trace see Section 2 5 5 To set the number of history entries stored by GHCi use fghci hist size n info name Displays information about the given name s For example if name is a class then the class methods and their types will be printed if name is a type constructor then its definition will be printed if name is a function then its type will be printed If name has been loaded from a source file then GHCi will also display the location of its definition in the source For types and classes GHCi also summarises instances that mention them To avoid showing irrelevant information an instance is shown only if a its head mentions name and b all the other things mentioned in the instance are in scope either qualified or otherwise as a result of a Load or module commands The command info works in a similar fashion b
617. tput of two compiler runs have many fewer gratuitous differences so you can realistically apply diff Once diff has shown you where to look you can try again without dsuppress uniques The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 107 327 dsuppress idinfo Suppress extended information about identifiers where they are bound This includes strictness infor mation and inliner templates Using this flag can cut the size of the core dump in half due to the lack of inliner templates dsuppress module prefixes Suppress the printing of module qualification prefixes This is the Data List in Data List length dsuppress type signatures Suppress the printing of type signatures dsuppress type applications Suppress the printing of type applications dsuppress coercions Suppress the printing of type coercions 4 18 4 Checking for consistency dcore lint Turn on heavyweight intra pass sanity checking within GHC at Core level It checks GHC s sanity not yours dstg lint Ditto for STG level NOTE currently doesn t work demm lint Ditto for C level 4 18 5 How to read Core syntax from some ddump flags Let s do this by commenting an example It s from doing ddump ds on this code skip2 m m skip2 m 2 Before we jump in a word about names of things Within GHC variables type constructors etc are identified by their Uniques These are of the form letter
618. tructor and one or more levels of indirection may be removed Unpacking only happens for single constructor datatypes Int is a good candidate for example Using funbox strict fields is only really a good idea in conjunction with O because otherwise the extra packing and unpacking won t be optimised away In fact it is possible that funbox strict fields may worsen performance even with O but this is unlikely let us know if it happens to you Use unboxed types a GHC extension When you are really desperate for speed and you want to get right down to the raw bits Please see Section 7 2 1 for some information about using unboxed types Before resorting to explicit unboxed types try using strict constructor fields and funbox strict fields first see above That way your code stays portable Use foreign import a GHC extension to plug into fast libraries This may take real work but There exist piles of massively tuned library code and the best thing is not to compete with it but link with it Chapter 8 describes the foreign function interface The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 151 327 Don t use Floats If you re using Complex definitely use Complex Double rather than Complex Float the former is specialised heavily but the latter isn t Floats probably 32 bits are almost always a bad idea anyway unless you Really Know What You Are Doing Use Doub
619. trusted by C Is it Well it is compiled with XSafe so the code in Buggle itself is machine checked to be OK but again under the assumption that all of Buggle s imports are trusted by C Prelude comes from base which C trusts and is compiled with XTrustworthy While Prelude is typically imported implicitly it still obeys the same rules outlined here So Buggle is considered trusted Notice that C didn t need to trust package Wuggle the machine checking is enough C only needs to trust packages that contain XTrustworthy modules 7 29 4 4 Trustworthy Requirements Module authors using the XTrust worthy language extension for a module M should ensure that M s public API the symbols exposed by its export list can t be used in an unsafe manner This mean that symbols exported should respect type safety and referential transparency 7 29 4 5 Package Trust Safe Haskell gives packages a new Boolean property that of trust Several new options are available at the GHC command line to specify the trust property of packages trust P Exposes package P if it was hidden and considers it a trusted package regardless of the package database distrust P Exposes package P if it was hidden and considers it an untrusted package regardless of the package database distrust all packages Considers all packages distrusted unless they are explicitly set to be trusted by subsequent command line options To set a package s trust
620. type Suppose instead we do not give a type signature asking GHC to infer it instead In this case GHC will refrain from simplifying the constraint C Int b for the same reason as before but rather than rejecting the program it will infer the type es Ci Pol gt a gt ol That postpones the question of which instance to pick to the call site for by which time more is known about the type b You can write this type signature yourself 1f you use the XFlexibleContexts flag Exactly the same situation can arise in instance declarations themselves Suppose we have class Foo a where E 388 gt a instance Foo b where f x and as before the constraint C Int b arises from s right hand side GHC will reject the instance complaining as before that it does not know how to resolve the constraint C Int b because it matches more than one instance declaration The solution is to postpone the choice by adding the constraint to the context of the instance declaration thus instance C Int b gt Foo b where f x You need XFlexibleInstances to do this Warning overlapping instances must be used with care They can give rise to incoherence i e different instance choices are made in different parts of the program even without XIncoherent Instances Consider The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 203 327 ry LANGUAGI OverlappingInstances module H
621. uce a visual parallel execution profile of the program e As text to standard output for debugging purposes 1 flags Log events in binary format to the file program eventlog Without any flags specified this logs a default set of events suitable for use with tools like ThreadScope For some special use cases you may want more control over which events are included The flags is a sequence of zero or more characters indicating which classes of events to log Currently these the classes of events that can be enabled disabled s scheduler events including Haskell thread creation and start stop events Enabled by default g GC events including GC start stop Enabled by default p parallel sparks sampled Enabled by default f parallel sparks fully accurate Disabled by default u user events These are events emitted from Haskell code using functions such as Debug Trace traceEvent Enable You can disable specific classes or enable disable all classes at once a enable all event classes listed above x disable the given class of events for any event class listed above or a for all classes For example 1 ag would disable all event classes a except for GC events g For spark events there are two modes sampled and fully accurate There are various events in the life cycle of each spark usually just creating and running but there are some more exceptional possibilities In the sampled mode the
622. ude is implicitly imported This happens unless either the Prelude module is explicitly imported with an import Prelude line or this implicit import is disabled either by XNoImplicitPrelude ora LANGUAGE NoImplicitPrelude pragma Note that no warning is given for syntax that implicitly refers to the Prelude even if KNoImplicitPrelude would change whether it refers to the Prelude For example no warning is given when 368 means Prelude fromInteger 368 Prelude Integer where Prelude refers to the actual Prelude module regardless of the imports of the module being compiled This warning is off by default The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 63 327 fwarn incomplete patterns fwarn incomplete uni patterns Theoption fwarn incomplete pat terns warns about places where a pattern match might fail at runtime The function g below will fail when applied to non empty lists so the compiler will emit a warning about this when fwarn incomplete patterns is enabled This option isn t enabled by default because it can be a bit noisy and it doesn t always indicate a bug in the program However it s generally considered good practice to cover all the cases in your functions and it is switched on by W The flag fwarn incomplete uni patterns is similar except that it applies only to lambda expressions and pattern bindings constructs that only allow a single pattern a NM
623. ue to its presence in a context see Sec tion 7 13 6 For example type Ta Monad m gt a gt fa It is recommended to write this polymorphic type as type T a forall m Monad m gt a gt a The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 66 327 instead fwarn wrong do bind Report expressions occurring in do and mdo blocks that appear to lack a binding For instance do return popInt 10 return 10 would report the first statement in the do block as suspicious as it has the type StackM StackM Int which consists of two nested applications of the same monad constructor but which is not then unpacked by binding the result The warning is suppressed by explicitly mentioning in the source code that your program is throwing something away do E lt gt ecu Io ae ING p certen LO For almost all sensible programs this will indicate a bug and you probably intended to write elo aos IL 6 seeicibueion 10 fwarn inline rule shadowing Warn if a rewrite RULE might fail to fire because the function might be inlined before the rule has a chance to fire See Section 7 23 3 If you re feeling really paranoid the dcore lint option is a good choice It turns on heavyweight intra pass sanity checking within GHC It checks GHC s sanity not yours 4 9 Packages A package is a library of Haskell modules known to the compiler GHC comes with several packages see the accompany
624. ues as described in the next section The operator must also not use any variable defined within the current arrow abstraction We could define our own operator untilA ArrowChoice a gt a e s gt a e s Bool gt a e s untilA body cond proc x gt D lt Cine K K if b then returnA lt else do DOC lt ox untilA body cond lt x and use it in the same way Of course this infix syntax only makes sense for binary operators there is also a more general syntax involving special brackets EOE gt ClO Wi Se 12 lt gerd GhateslIVN Ecce lt sary lc 56 lt 3 1 7 18 4 Primitive constructs Some operators will need to pass additional inputs to their subcommands For example in an arrow type supporting exceptions the operator that attaches an exception handler will wish to pass the exception that occurred to the handler Such an operator might have a type meamea 88 CS S a Se kes lt gt a SS where Ex is the type of exceptions handled You could then use this with arrow notation by writing a command body handleA ex gt handler so that if an exception is raised in the command body the variable ex is bound to the value of the exception and the command handler which typically refers to ex is entered Though the syntax here looks like a functional lambda we are talking about commands and something different is going on The input to the arrow represen
625. ule M the constraint E a Int should be improved by setting a T even though there is no explicit mention of T in M These considerations lead to the following definition of an orphan module e An orphan module contains at least one orphan instance or at least one orphan rule e An instance declaration in a module M is an orphan instance if The class of the instance declaration is not declared in M and Either the class has no functional dependencies and none of the type constructors in the instance head is declared in M or there is a functional dependency for which none of the type constructors mentioned in the non determined part of the instance head is defined in M Only the instance head counts In the example above it is not good enough for C s declaration to be in module A it must be the declaration of D or T e A rewrite rule in a module M is an orphan rule if none of the variables type constructors or classes that are free in the left hand side of the rule are declared in M If you use the flag fwarn orphans GHC will warn you if you are creating an orphan module Like any warning you can switch the warning off with fno warn orphans and Werror will make the compilation fail if the warning is issued You can identify an orphan module by looking in its interface file M hi using the show iface mode If there is a orphan module on the first line GHC considers it an orphan module 4 8 Warnings and sanity
626. ule M compiled with XSafe are dropped RULES defined in trustworthy modules that M imports are still valid and will fire as usual OverlappingInstances This extension can be used to violate semantic consistency because malicious code could redefine a type instance by containing a more specific instance definition in a way that changes the behaviour of code importing the untrusted module The extension is not disabled for a module M compiled with XSafe but restricted While M can define overlapping instance declarations they can only overlap other instance declaration defined in M If in a module N that imports M at a call site that uses a type class function there is a choice of which instance to use i e an overlap and the most specific instances is from M then all the other choices must also be from M If not a compilation error will occur A simple way to think of this is a same origin policy for overlapping instances defined in Safe compiled modules Data Typeable We restrict Typeable instances to only derived ones offered by GHC through the XDeriveDataTypeable extension Hand crafted instances of the Typeable type class are not allowed in Safe Haskell as this can easily be abused to unsafely coerce between types 7 29 3 Safe Imports Safe Haskell enables a small extension to the usual import syntax of Haskell adding a safe keyword impdecl gt import safe qualified modid as modid impspec When used the module bei
627. ule or import to try bring into scope a non loaded module may result in the message module M is not loaded 2 4 6 The main and run commands When a program is compiled and executed it can use the get Args function to access the command line arguments However we cannot simply pass the arguments to the main function while we are testing in ghci as the main function doesn t take its directly Instead we can use the main command This runs whatever main is in scope with any arguments being treated the same as command line arguments e g Prelude gt let main System Environment getArgs gt gt print Prelude gt main foo bar EROON TSn We can also quote arguments which contains characters like spaces and they are treated like Haskell strings or we can just use Haskell list syntax Prelude gt main foo bar baz a Yoa oci Prelnide mmama AOO bar baz LP Leo bare han Finally other functions can be called either with the main is flag or the run command Prelude gt let foo putStrLn foo gt gt System Environment getArgs gt gt print Prelude gt let bar putStrLn bar gt gt System Environment getArgs gt gt print Prelude gt set main is foo Prelude gt main foo bar baz foo taste ised ea Prelude gt run bar foo bar baz bar Eros Moria oeira The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 22 327 2 4 7
628. ur platform For example if we specify a Haskell library as HSfoo in the package spec then the various flavours of library that GHC actually uses will be called libHSfoo a The name of the library on Unix and Windows mingw systems Note that we don t support building dynamic libraries of Haskell code on Unix systems HSfoo dl1 The name of the dynamic library on Windows systems optional HSfoo o HSfoo obj The object version of the library used by GHCi extra libraries string list 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 1ibHSbase_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 ext ra libraries The libraries listed in ext ra libraries may be any libraries supported by your system s linker including dynamic libraries so on Unix DLL on Windows Also ext ra libraries are placed on the linker command line after the hs libraries for the same package If your package has dependencies in the other direction i e ext ra libraries depends on hs libraries and the libraries are static you might need to make tw
629. urce We don t recommend building packages the hard way Instead use the Cabal infrastructure if possible If your package is particularly complicated or requires a lot of configuration then you might have to fall back to the low level mechanisms so a few hints for those brave souls follow You need to build an installed package info file for passing to ghc pkg when installing your package The contents of this file are described in Section 4 9 9 The Haskell code in a package may be built into one or more archive libraries e g 1ibHSfoo a or a single shared object e g 1ibHSfoo d11 so dylib The restriction to a single shared object is because the package system is used to tell the compiler when it should make an inter shared object call rather than an intra shared object call call inter shared object calls require an extra indirection e Building a static library is done by using the ar tool like so are coe Libigitoo l 0 a 200 13 0 CoO cas where A o B o and so on are the compiled Haskell modules and 1ibHS foo a is the library you wish to create The syntax may differ slightly on your system so check the documentation if you run into difficulties e To load a package foo GHCi can load its 1ibHSfoo a library directly but it can also load a package in the form of a single HSfoo o file that has been pre linked Loading the o file is slightly quicker but at the expense of having another copy of the compiled package The ru
630. us of modules when using safe inference Works on all fwarn safe module types even those dynamic fno warn saf using explicit Safe Haskell modes such as XTrustworthy and so can be used to have the compiler check any assumptions made warn if the module being compiled is marked as XTrustworthy but it could instead be marked as fwarn XSafe a more trustworthy safe informative bound Can be used to detect once a Safe Haskell bound can be improved as dependencies are updated dynamic fno warn saf The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 120 327 Flag Description Static Dynamic Reverse fwarn warnings deprecations warn about uses of functions amp types that have warnings or deprecated pragmas dynamic fno warn warnings deprecations fwarn amp deprecated warn on definitions conflicting with the Applicative Monad Proposal AMP dynamic fno warn amp fwarn typed hol Report warnings when typed hole errors are deferred until runtime See fdefer typed holes dynamic fno warn typed holes fwarn partial type signatures warn about holes in partial type signatures when XPartialTypesignat ures is enabled Not applicable when XParti alTypesignatures is not enabled in which case errors are generated for such holes See Section 7 15 dynamic
631. us type solving will fail For example consider the earlier definition C a gt Int 88 2 gt lote O os op 32 Co ck He lat Gea In g s definition we ll instantiate to C alpha and try to deduce C alpha from C a and fail So in fact we use this as our definition of ambiguity a type t y is ambiguious if and only if undefined ty ty would fail to typecheck We use a very similar test for inferred types to ensure that they too are unambiguous Switching off the ambiguity check Even if a function is has an ambiguous type according the guiding principle 1t is possible that the function is callable For example class D a b where instance D Bool b where strange Dab gt a gt a Serange o INRE foo strange True The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 227 1327 Here st range s type is ambiguous but the call in foo is OK because it gives rise to a constraint D Bool beta which is soluble by the D Bool b instance So the language extension XAllowAmbiguousTypes allows you to switch off the ambiguity check But even with ambiguity checking switched off GHC will complain about a function that can never be called such as this one Loy Plat Bool gt ao gt 2 A historical note GHC used to impose some more restrictive and less principled conditions on type signatures For type type forall tvl tvn cl cn gt type GHC used to require a
632. use the bytecode compiler can t deal with unboxed tuples Concurrent threads don t carry on running when GHCi is waiting for input This should work as long as your GHCi was built with the threaded switch which is the default Consult whoever supplied your GHCi installation The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 42 327 After using getContents I can t use stdin again until Ido load or reload This is the defined behaviour of get Contents it puts the stdin Handle in a state known as semi closed wherein any further I O operations on it are forbidden Because I O state is retained between computations the semi closed state persists until the next load or reload command You can make stdin reset itself after every evaluation by giving GHCi the command set r This works because stdin is just a top level expression that can be reverted to its unevaluated state in the same way as any other top level expression CAF I can t use Control C to interrupt computations in GHCi on Windows See Section 12 2 The default buffering mode is different in GHCi to GHC In GHC the stdout handle is line buffered by default However in GHCi we turn off the buffering on stdout because this is normally what you want in an interpreter output appears as it is generated If you want line buffered behaviour as in GHC you can start your program thus main do hSetBuffering stdout LineBuffering
633. used with either of the two dynload modes though it makes most sense with the deploy mode The difference is that with the deploy mode the above example will end up with an ELF RUNPATH of just SORIGIN while with the sysdep mode the RUNPATH will be SORIGIN followed by all the library directories of all the packages that the program depends on e g base and rts packages etc which are typically absolute paths The unix tool readelf dynamic is handy for inspecting the RPATH RUNPATH entries in ELF shared libraries and executables 4 13 4 2 Mac OS X The standard assumption on Darwin Mac OS X is that dynamic libraries will be stamped at build time with an install name which is the full ultimate install path of the library file Any libraries or executables that subsequently link against it even if it hasn t been installed yet will pick up that path as their runtime search location for it When compiling with ghc directly the install name is set by default to the location where it is built You can override this with the dylib install name option which passes install_name to the Apple linker Cabal does this for you It automatically sets the install name for dynamic libraries to the absolute path of the ultimate install location 4 14 Using Concurrent Haskell GHC supports Concurrent Haskell by default without requiring a special option or libraries compiled in a certain way To get access to the support libraries for Concurrent Has
634. ut it removes restriction b showing all instances that are in scope and mention name in their head issafe module Displays Safe Haskell information about the given module or the current module if omitted This in cludes the trust type of the module and its containing package The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 36 327 kind type Infers and prints the kind of type The latter can be an arbitrary type expression including a partial applica tion of a type constructor such as Either Int In fact kind even allows you to write a partial application of a type synonym usually disallowed so that this works ghci gt type T a b a b a Gilneas gik A Wale BOOL AE OO ee Oe cinco gis Ae oe SB ot See cents le Il lao I IGE ea o E If you specify the optional GHC will in addition normalise the type by expanding out type synonyms and evaluating type function applications and display the normalised result list identifier Lists the source code around the definition of identifier or the current breakpoint if not given This requires that the identifier be defined in an interpreted module If your output device supports it then GHCi will highlight the active subexpression in bold list module line Lists the source code around the given line number of module This requires that the module be interpreted If your output device supports it then GHCi will highli
635. utput option allows for tools to use hpc to glean coverage hpc help report Usage hpc report OPTION lt TIX_FILE gt lt MODULE gt lt MODULE gt 1 Options per module show module level detail decl list show unused decls exclude PACKAGE MODULE exclude MODULE and or PACKAGE include PACKAGE MODULE include MODULE and or PACKAGE SECC sie path to source directory of hs files multi use of srcdir possible hpcdir DIR append sub directory that contains mix files default hpc rarely used reset hpcdirs empty the list of hpcdir s rarely used obte able show output in XML 5 7 3 2 hpc markup hpc markup marks up source files into colored html hpc help markup Usage hpc markup OPTION lt TIX_FILE gt lt MODULE gt lt MODULE gt 1 Options The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 146 327 exclude PACKAGI include PACKAGI srcdir DIR hpcdir DIR MODU MODU a nal reset hpcdirs fun entry count highlight covered destdir DIR 5 7 3 3 hpc sum exclude MODULE include MODULI path to source directory of and or PACKAG and or PACKAG leal deal multi use of srcdir possible append sub directory that contains default hpc ee arely used empty the list of hpcdir s rarely used show
636. utput is discarded The arrow returnA is defined in the Control Arrow module as arr id The above example is treated as an abbreviation for A E gt SN gt seh SSS a gt awe A Wn E gt Ye Es w See RL gt gt g gt arr snd gt gt gt are A Ca Y gt let z xy ina E 2 21 gt gt gt miesat lari N Gk E Se in gt gt auae Ge 2 gt gt returnA Note that variables not used later in the composition are projected out After simplification using rewrite rules see Section 7 23 defined in the Control Arrow module this reduces to arr Q E gt ELESE E SSS eie N A ZA ee V See mirst G gt gt are Cr amp y gt let a xty an Ez Z gt gt Else I gt gt gt aie Ge 2 tet which is what you might have written by hand With arrow notation GHC keeps track of all those tuples of variables for you Note that although the above translation suggests that 1et bound variables like z must be monomorphic the actual translation produces Core so polymorphic variables are allowed It s also possible to have mutually recursive bindings using the new rec keyword as in the following example counter ArrowCircuit a gt a Bool Int counter proc reset gt do rec output lt returnA lt if reset then 0 else next next lt delay 0 lt output 1 FetuenaA lt SOUCOuUt The translation of such forms uses the Loop combinator so the arrow concerned must belong
637. utput s o a oo a 52 4 7 3 Keeping Intermediate Files oie A RA as 53 4 7 6 Redirecting temporary files gt 2 2 2 0 2 0 00 00000000000 00022 peee 33 4 7 7 Other options related to interface files e 53 4 7 8 The recompilation checker 0 00 00 002 eee E 54 4 7 9 How to compile mutually recursive modules 2 2 2 0 0 2 0 0 0 000 000 0000 54 4 7 10 Module signatures 56 4 741 sme make 2 coi a Ra a Ge EERO RGSS a a od amp ak 37 4 7 12 Dependency generation 58 4 7 13 Orphan modules and instance declarations a 59 Warnings and sanity checking oaoa ee 60 Packages si eo e eami e a ala e a a 2 66 49 1 Usine Packages Di 2 25 sd amp tig ea ie A A e ae A E e Gg 66 49 2 Thema package sp songpk eaee e e a ae a aE e a a E a E base a 68 4 9 3 Consequences of packages for the Haskell language a 69 4 9 4 Thinning and renaming modules 69 4 9 3 Package Databases o aicen s os E eG ee ee el ew A ee ee E 69 4 9 5 1 The GHC_PACKAGE_PATH environment variable 70 4 9 6 Installed package IDs dependencies and broken packages o o e 70 4 9 7 Package management the ghc pkg command 0 0 2 e eee eee ee eee 72 4 9 8 Building a package from Haskell source o a 74 49 9 InstalledPackageInfo a package specification o o e e 75 4 9 10 Package environments
638. valuated and is discarded from the pool by the garbage collector Any remaining sparks are discarded at the end of execution so converted plus pruned does not necessarily add up to the total e Next there is the CPU time and wall clock time elapsed broken down by what the runtime system was doing at the time INIT is the runtime system initialisation MUT is the mutator time i e the time spent actually running your code GC is the time spent doing garbage collection RP is the time spent doing retainer profiling PROF is the time spent doing other profiling EXIT is the runtime system shutdown time And finally Total is of course the total GC time tells you what percentage GC is of Total Alloc rate tells you the bytes allocated in the heap divided by the MUT CPU time Productivity tells you what percentage of the Total CPU and wall clock elapsed times are spent in the mutator MUT The S flag as well as giving the same output as the s flag prints information about each GC as it happens Alloc Copied Live GC GC TOT TOT Page Flts bytes bytes bytes user elap user elap 528496 47728 MISE OO 0 02 OO 0 02 0 O Gen 1 gare 524944 175944 ASS O 0 00 0 08 QoL 0 0 Ceng 0 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 102 327 For each garbage collection we print How many bytes we allocated this garbage collection How many bytes we copied this garbage collection How many bytes are
639. variable in this way GHC insists that the type variable is bound to a rigid or fully known type variable This means that any user written type signature always stands for a completely known type If all this seems a little odd we think so too But we must have some way to bring such type variables into scope else we could not name existentially bound type variables in subsequent type signatures This is now the only situation in which a pattern type signature is allowed to mention a lexical variable that is not already in scope For example both and y would be illegal if a was not already in scope 7 13 8 5 Class and instance declarations The type variables in the head of a class or instance declaration scope over the methods defined in the where part For example class C a where as Be fall gt a op xs let ys a ys reverse xs in head ys The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 237 327 7 13 9 Bindings and generalisation 7 13 9 1 Switching off the dreaded Monomorphism Restriction Haskell s monomorphism restriction see Section 4 5 5 of the Haskell Report can be completely switched off by XNoMono morphismRestriction Since GHC 7 8 1 the monomorphism restriction is switched off by default in GHCi s interactive options see Section 2 8 3 7 13 9 2 Generalised typing of mutually recursive bindings The Haskell Report specifies that a group of bindings at top leve
640. ve function The principal reason do to so to allow later use of SPECIALISE 7 22 6 3 NOINLINE pragma The NOINLINE pragma does exactly what you d expect it stops the named function from being inlined by the compiler You shouldn t ever need to do this unless you re very cautious about code size NOTINLINE is a synonym for NOINLINE NOINLINE is specified by Haskell 98 as the standard way to disable inlining so it should be used if you want your code to be portable 7 22 6 4 CONLIKE modifier An INLINE or NOINLINE pragma may have a CONLIKE modifier which affects matching in RULEs only See Section 7 23 4 7 22 6 5 Phase control Sometimes you want to control exactly when in GHC s pipeline the INLINE pragma is switched on Inlining happens only during runs of the simplifier Each run of the simplifier has a different phase number the phase number decreases towards zero If you use dverbose core2core you ll see the sequence of phase numbers for successive runs of the simplifier In an INLINE pragma you can optionally specify a phase number thus e INLINE k f means do not inline f until phase k but from phase k onwards be very keen to inline it e INLINE k f means be very keen to inline f until phase k but from phase k onwards do not inline it e NOINLINE k f means do not inline f until phase k but from phase k onwards be willing to inline it as if there was no pragma
641. vel functions is good software engineering practice anyway Tip using fwarn missing signatures can help enforce good signature practice The automatic specialisation of overloaded functions with 0 should take care of overloaded local and or unex ported functions Use SPECIALIZE pragmas Specialize the overloading on key functions in your program See Section 7 22 9 and Sec tion 7 22 10 But how do I know where overloading is creeping in A low tech way grep search your interface files for over loaded type signatures You can view interface files using the show iface option see Section 4 7 7 ghc show iface Foo hi egrep a z gt Strict functions are your dear friends and among other things lazy pattern matching is your enemy If you don t know what a strict function is please consult a functional programming textbook A sentence or two of explanation here probably would not do much good Consider these two code fragments E M dgls lt lt Y 200 y Suele f arg let Wibble x y arg in lazy The former will result in far better code A less contrived example shows the use of cases instead of lets to get stricter code a good thing f Wibble x y beautiful but slow let al bl cl unpackFoo x a2 b2 c2 unpackFoo y Wil pac The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 150 327 f Wibble x y ugly
642. we have a closed expression See tT Ore al eae ul cee ts the static form is of type Suelo ces Hiosa alo ss y loss EL gt Strate CP tie sit Furthermore type t is constrained to have a Typeable instance The following are therefore illegal static show No Typeable instance for Show a gt a gt String static Control Monad ST runST No Typeable instance for forall s That being said with the appropriate use of wrapper datatypes the above limitations induce no loss of generality LANGUAGE ConstraintKinds LANGUAGE DeriveDataTypeable LANGUAGE ExistentialQuantification LANGUAGE Rank2Types id LANGUAGE StandaloneDeriving LANGUAGE StaticPointers import Control Monad ST import Data Typeable iio CHC STE acl tc ie cla a Dake gt Dalek deriving Typeable Gilets Ly pcabille e gt Sitaelch ta DICE Sno a gt El Sie ean G gl static Dict gt show data Rank2Wrapper f R2W forall s f s deriving Typeable mewes bajo ae a e lao timido 9s ae Sel deriving Typeable g2 Typeable a gt StaticPtr Rank2Wrapper Flip ST a gt a GA static R2W f gt runST unFlip f 7 22 Pragmas GHC supports several pragmas or instructions to the compiler placed in the source code Pragmas don t normally affect the meaning of the program but they might affect the efficiency of the generated code Pragmas all take the
643. wise don t apply as they change the semantics of the program when applied to lazy arguments fstrictness before n Run an additional strictness analysis before simplifier phase n The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 83 327 funbox small strict fields On by default This option causes all constructor fields which are marked strict i e 1 and which representation is smaller or equal to the size of a pointer to be unpacked if possible It is equivalent to adding an UNPACK pragma see Section 7 22 11 to every strict constructor field that fulfils the size restriction For example the constructor fields in the following data types data A A Int clima 1 gt 18 IA newtype C C B data D D C would all be represented by a single Int see Section 7 2 value with funbox small strict fields enabled This option is less of a sledgehammer than funbox strict fields it should rarely make things worse If you use funbox small strict fields to turn on unboxing by default you can disable it for certain constructor fields using the NOUNPACK pragma see Section 7 22 12 Note that for consistency Double Word64 and Int 64 constructor fields are unpacked on 32 bit platforms even though they are technically larger than a pointer on those platforms sey funbox strict fields This option causes all constructor fields which are marked strict i e to be unpacked if
644. without its parent type constructor see Section 7 3 9 2 7 3 27 Summary of stolen syntax Turning on an option that enables special syntax might cause working Haskell 98 code to fail to compile perhaps because it uses a variable name which has become a reserved word This section lists the syntax that is stolen by language extensions We use notation and nonterminal names from the Haskell 98 lexical syntax see the Haskell 98 Report We only list syntax changes here that might affect existing working programs i e stolen syntax Many of these extensions will also enable new context free syntax but in all cases programs written to use the new syntax would not be compilable without the option enabled There are two classes of special syntax e New reserved words and symbols character sequences which are no longer available for use as identifiers in the program e Other special syntax sequences of characters that have a different meaning when this particular option is turned on The following syntax is stolen forall Stolen in types by XExplicitForAll and hence by XScopedTypeVariables XLiberalTypeSy nonyms XRankNTypes XExistentialQuantification mdo Stolen by XRecursiveDo foreign Stolen by XForeignFunctionInterface rec proc lt gt lt lt gt gt and brackets Stolen by XArrows The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 177 327 varid
645. wn to the compiler at its binding site The easiest way to ensure that a variable a rigid type is to give it a type signature For more precise details see Simple unification based type inference for GADTs The criteria implemented by GHC are given in the Appendix 7 5 Extensions to the deriving mechanism 7 5 1 Inferred context for deriving clauses The Haskell Report is vague about exactly when a deriving clause is legal For example The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 188 327 data data data 10 E E Wil a We 1 a oll SR teh i hi eS deriving Eq deriving Eq deriving Eq The natural generated Eq code would result in these instance declarations 0 f a where instance Eq a gt Eq instance Eq f a gt Eq instance Eq a gt Eq 1 f a where 2 f a where The first of these is obviously fine The second is still fine although less obviously The third is not Haskell 98 and risks losing termination of instances GHC takes a conservative position it accepts the first two but not the third The rule is this each constraint in the inferred instance context must consist only of type variables with no repetitions This rule is applied regardless of flags If you want a more exotic context you can write it yourself using the standalone deriving mechanism 7 5 2 Stand alone deriving declaration
646. wo are equivalent Not so for pattern synonyms the two forms are different in order to distinguish the two cases above See Trac 9953 for discussion of this choice 7 3 9 4 Matching of pattern synonyms A pattern synonym occurrence in a pattern is evaluated by first matching against the pattern synonym itself and then on the argument patterns For example in the following program f and f are equivalent Pattern Par sy lt lt y f Pair True True Tru EPE False ie E yi Thoe lt True lt y Trie ie False Note that the strictness of differs from that of g defined below g True True Tru Sia False Main gt f False undefined xxx Exception Prelude undefined Main gt g False undefined False The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 163 327 7 3 10 n k patterns n k pattern support is disabled by default To enable it you can use the XNP lusKPatterns flag 7 3 11 Traditional record syntax Traditional record syntax such as C f x is enabled by default To disable it you can use the XNoTraditionalReco rdSyntax flag 7 3 12 The recursive do notation The do notation of Haskell 98 does not allow recursive bindings that is the variables bound in a do expression are visible only in the textually following code block Compare this to a let expression where bound variables are visible in the entire binding group It tur
647. xtensions are described in Section 8 1 but please note that programs using these features are not portable Hence these features should be avoided where possible The FFI libraries are documented in the accompanying library documentation see for example the Foreign module 8 1 GHC extensions to the FFI Addendum The FFI features that are described in this section are specific to GHC Your code will not be portable to other compilers if you use them 8 1 1 Unboxed types The following unboxed types may be used as basic foreign types see FFI Addendum Section 3 2 Int Word Char Float Double Addr StablePtr a MutableByteArray ForeignObj and ByteArray 8 1 2 Newtype wrapping of the lO monad The FFI spec requires the IO monad to appear in various places but it can sometimes be convenient to wrap the IO monad in a newtype thus newtype MyIO a MIO IO a A reason for doing so might be to prevent the programmer from calling arbitrary IO procedures in some part of the program The Haskell FFI already specifies that arguments and results of foreign imports and exports will be automatically unwrapped if they are newtypes Section 3 2 of the FFI addendum GHC extends the FFI by automatically unwrapping any newtypes that wrap the IO monad itself More precisely wherever the FFI specification requires an IO type GHC will accept any newtype wrapping of an IO type For example these declarations are OK forelga m
648. y f XDeriveAnyClass diass dynamic XNoDeriveAnyClass XDeriveDataTypea airis OFRE MA XNoDeriveDataType a LV i EN a class Implied by XAutoD dynamic wi ble able riveTypeabl Enable deriving for the XDeriveFunctor Functor class Implied by dynamic XNoDeriveFunctor XDeriveTraversabl Enable deriving for the Foldable class Implied b E XDeriveFoldable E dable p y dynamic XNoDeriveFoldable XDeriveTraversabl Enable deriving for the XDeriveGeneric dynamic XNoDeriveGeneric Generic class Enable deriving for the Traversable class Implies XNoDeriveTraversa dynamic XDeriveTraversabl XDeriveFunctor and ble XDeriveFoldable f Enable record field XDisambiguateReco XNoDisambiguateRe i disambiguation Implied by dynamic i rdFields cordFields XRecordWildCards Allow empty case XEmptyCase dynamic XNoEmptyCase alternatives The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 114 327 Flag Description Static Dynamic Reverse XEmptyDataDecls Enable empty data declarations dynamic XNoEmptyDataDecls XExistentialQuant ification Enable existential quantification dynamic XNoExistentialQua ntification XExplicitForAll Enable explicit universal quantification Implied by XScopedTypeVariab les XLiberalTypeSy nonyms XRankNTypes and XExistentialQu
649. y 2 5 SOR alae 2s LAS 6 8 ES ES 1 0 S 55 lt end of history gt lt exception thrown gt Main gt back Logged breakpoint at qgsort hs 3 24 38 result lt eal as ss lal AE EA Sis sore isso 24 ciel Man e orce als xxx Exception Prelude undefined ISS oras 28 aMann gt print sas as br y tel y oie sien The exception itself is bound to a new variable _exception Breaking on exceptions is particularly useful for finding out what your program was doing when it was in an infinite loop Just hit Control C and examine the history to find out what was going on 2 5 7 Example inspecting functions It is possible to use the debugger to examine function values When we are at a breakpoint and a function is in scope the debugger cannot show you the source code for it however it is possible to get some information by applying it to some arguments and observing the result The process is slightly complicated when the binding is polymorphic We show the process by means of an example To keep things simple we will use the well known map function import Prelude hiding map map a gt b gt a gt b MAA I MAP EAS 16 32 ES We set a breakpoint on map and call it The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 31 327 Main gt break 5 Breakpoint 0 activated at map hs 5 15 28 Main gt map Just 1 5 Stopped at map hs 4 0 5 12 result
650. y are Apple s way of packaging shared libraries To link to Apple s Carbon API for example you d use framework Carbon staticlib On Darwin OS X iOS only link all passed files into a static library suitable for linking into an iOS when using a cross compiler or Mac Xcode project To control the name use the o name option as usual The default name is liba a This should nearly always be passed when compiling for iOS with a cross compiler The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 89 327 Ldir Where to find user supplied libraries Prepend the directory dir to the library directories path framework pathdir On Darwin OS X iOS only prepend the directory dir to the framework directories path This option corresponds to the F option for Apple s Linker F already means something else for GHC split objs 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 This only makes sense for libraries where it means that executables linked against the library are smaller as they only link against the object files that they need However assembling all the sections separately is expensive so this is slower than compiling normally Additionally the size of the library itself the a file can be a factor of 2 to 2 5 larger We use this feature for building GHC s libraries stat
651. y module that imports a safe language module expressions that compile both with and without the safe import have the same meaning in both cases That is importing a module using the safe language cannot change the meaning of existing code that isn t dependent on that module So for example there are some restrictions placed on the Overlapping Instances extension as it can violate this property These three properties guarantee that in the safe language you can trust the types can trust that module export lists are respected and can trust that code that successfully compiles has the same meaning as it normally would Lets now look at the details of the safe language In the safe language dialect enabled by XSafe we disable completely the following features e TemplateHaskell Is particularly dangerous as it can cause side effects even at compilation time and can be used to access constructors of abstract data types In the safe language dialect we restrict the following features The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 283 327 ForeignFunctionInterface This is mostly safe but foreign import declarations that import a function with a non IO type are disallowed All FFI imports must reside in the IO Monad RULES As they can change the behaviour of trusted code in unanticipated ways violating semantic consistency they are restricted in function Specifically any RULES defined in a mod
652. ype CProv CReq gt EL gt LE2 gt con gt UN gt u So in the previous example when used in an expression ExNumPat has type ExNumPat Show b Num a Eq a gt b gt Tt Notice that this is a tiny bit more restrictive than the expression MkT 42 x which would not require Eq a Consider these two pattern synonyms data S a where Si 32 Bool gt Bool paccertmi Pil ly Just ly Pil 8 Bool gt Maybe Bool crema 122 do SL do P2 b Bool gt Bool gt S b E 83 Mess E gt Sicilia E 19 mo mo ma Type incorrect SS 28 gt Stilo g P2 b yes yes yes Fin Pattern P1 can only match against a value of type Maybe Bool so function f is rejected because the type signature is Maybe a To see this imagine expanding the pattern synonym On the other hand function g works fine becuase matching against P2 which wraps the GADT S provides the local equal ity a Bool If you were to give an explicit pattern signature P2 Bool gt S Bool then P2 would become less polymorphic and would behave exactly like P1 so that g would then be rejected In short if you want GADT like behaviour for pattern synonyms then unlike unlike concrete data constructors like S1 you must write its type with explicit provided equalities For a concrete data construoctr like S1 you can write its type signature as eigher S1 Bool gt S BoolorS1 b Bool gt Bool gt S b the t
653. ype T forall a Ord a gt MkT a Reason a value of type T must be represented as a pair of a dictionary for Ord t and a value of type t That contradicts the idea that newt ype should have no concrete representation You can get just the same efficiency and effect by using data instead of newt ype If there is no overloading involved then there is more of a case for allowing an existentially quantified newt ype because the data version does carry an implementation cost but single field existentially quantified constructors aren t much use So the simple restriction no existential stuff on newt ype stands unless there are convincing reasons to change it e You can t use deriving to define instances of a data type with existentially quantified data constructors Reason in most cases it would not make sense For example The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 183 327 data T forall a MkT a deriving Eq To derive Eq in the standard way we would need to have equality between the single component of two MkT constructors instance Eq T where MkT a MkT b But a and b have distinct types and so can t be compared It s just about possible to imagine examples in which the derived instance would make sense but it seems altogether simpler simply to prohibit such declarations Define your own instances 7 4 7 Declaring data types with explicit constructor signature
654. ype error such as typing reverse True at the prompt you would get a warning and then an immediately following type error when the expression is evaluated This exception doesn t apply to statements as the following example demonstrates Prelude gt let x True 1 a lt interactive gt 3 16 Warning No instance for Num Char arising from the literal 1 The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 244 327 Possible fix add an instance declaration for Num Char In the first argument of namely 1 In the expression EY In the expression True a Prelude gt fst x TUS 7 17 Template Haskell Template Haskell allows you to do compile time meta programming in Haskell The background to the main technical innova tions is discussed in Template Meta programming for Haskell Proc Haskell Workshop 2002 There is a Wiki page about Template Haskell at http www haskell org haskellwiki Template_Haskell and that is the best place to look for further details You may also consult the online Haskell library reference material look for module Language Haskell TH Many changes to the original design are described in Notes on Template Haskell version 2 Not all of these changes are in GHC however The first example from that paper is set out below Section 7 17 4 as a worked example to help get you started The documentation here describes the realis
655. ytes default 128 GHC will allocate non pinned arrays of statically known size in the current nursery block if they re no bigger than n bytes ignoring GC overheap This value should be quite a bit smaller than the block size typically 4096 dynamic Hh max inlin memcpy insns n Inline memcpy calls if they would generate no more than n pseudo instructions default 32 dynamic Hh max inlin memset insns n Inline memset calls if they would generate no more than n pseudo instructions default 32 dynamic fmax relevant binds n Set the maximum number of bindings to display in type error messages default 6 dynamic fno max relevant bindings fmax simplifier iterations n Set the max iterations for the simplifier default 4 dynamic Hh max worker args If a worker has that many arguments none will be unpacked anymore default 10 dynamic fno opt coercion Turn off the coercion optimiser static fno pre inlining Turn off pre inlining dynamic The Glorious Glasgow Haskell Compilation System User s Guide Version 7 10 2 123 327 Flag Description Static Dynamic Reverse fno state hack Turn off the state hack whereby any lambda with a real world state token as argument is considered to be single entry Hence OK to inline things inside it static fo

The Glorious Glasgow Haskell Compilation System User`s Guide

Contents

Download Pdf Manuals

Related Search

Related Contents