GHC User's Guide Documentation
Total Page:16
File Type:pdf, Size:1020Kb
GHC User’s Guide Documentation Release 8.8.0.20190721 GHC Team Jul 22, 2019 CONTENTS 1 The Glasgow Haskell Compiler License 3 2 Introduction to GHC 5 2.1 Obtaining GHC ........................................ 5 2.2 Meta-information: Web sites, mailing lists, etc. .................... 5 2.3 Reporting bugs in GHC ................................... 6 2.4 GHC version numbering policy .............................. 6 3 Release notes for version 8.8.1 9 3.1 Highlights ........................................... 9 3.2 Full details ........................................... 9 3.2.1 Language ....................................... 9 3.2.2 Compiler ........................................ 10 3.2.3 LLVM backend .................................... 11 3.2.4 Runtime system ................................... 11 3.2.5 Template Haskell .................................. 11 3.2.6 ghc-prim library ................................... 12 3.2.7 ghc library ...................................... 12 3.2.8 base library ...................................... 12 3.2.9 Build system ..................................... 12 3.3 Included libraries ...................................... 12 4 Using GHCi 15 4.1 Introduction to GHCi .................................... 15 4.2 Loading source files ..................................... 16 4.2.1 Modules vs. filenames ............................... 17 4.2.2 Making changes and recompilation ....................... 17 4.3 Loading compiled code ................................... 17 4.4 Interactive evaluation at the prompt ........................... 19 4.4.1 I/O actions at the prompt .............................. 20 4.4.2 Using do notation at the prompt ......................... 20 4.4.3 Multiline input .................................... 22 4.4.4 Type, class and other declarations ........................ 23 4.4.5 What’s really in scope at the prompt? ...................... 24 The effect of :load on what is in scope ...................... 25 Controlling what is in scope with import ..................... 25 Controlling what is in scope with the :module command ........... 26 Qualified names .................................... 26 :module and :load .................................. 27 4.4.6 The :main and :run commands .......................... 27 4.4.7 The it variable .................................... 28 i 4.4.8 Type defaulting in GHCi .............................. 28 Interactive classes .................................. 30 Extended rules around default declarations .................. 30 4.4.9 Using a custom interactive printing function .................. 30 4.4.10 Stack Traces in GHCi ................................ 31 4.5 The GHCi Debugger ..................................... 32 4.5.1 Breakpoints and inspecting variables ...................... 32 Setting breakpoints .................................. 35 Listing and deleting breakpoints .......................... 35 4.5.2 Single-stepping .................................... 36 4.5.3 Nested breakpoints ................................. 36 4.5.4 The _result variable ................................ 37 4.5.5 Tracing and history ................................. 37 4.5.6 Debugging exceptions ............................... 39 4.5.7 Example: inspecting functions .......................... 40 4.5.8 Limitations ...................................... 41 4.6 Invoking GHCi ........................................ 41 4.6.1 Packages ....................................... 42 4.6.2 Extra libraries .................................... 42 4.7 GHCi commands ....................................... 43 4.8 The :set and :seti commands .............................. 53 4.8.1 GHCi options ..................................... 53 4.8.2 Setting GHC command-line options in GHCi .................. 54 4.8.3 Setting options for interactive evaluation only ................. 54 4.9 The .ghci and .haskeline files .............................. 55 4.9.1 The .ghci files .................................... 55 4.9.2 The .haskeline file ................................. 57 4.10 Compiling to object code inside GHCi .......................... 57 4.11 Running the interpreter in a separate process ..................... 57 4.12 FAQ and Things To Watch Out For ............................ 58 5 Using runghc 59 5.1 Usage .............................................. 59 5.2 runghc flags .......................................... 59 5.3 GHC Flags ........................................... 59 6 Using GHC 61 6.1 Using GHC ........................................... 61 6.1.1 Getting started: compiling programs ...................... 61 6.1.2 Options overview .................................. 62 Command-line arguments .............................. 62 Command line options in source files ....................... 62 Setting options in GHCi ............................... 63 6.1.3 Dynamic and Mode options ............................ 63 6.1.4 Meaningful file suffixes ............................... 63 6.1.5 Modes of operation ................................. 64 Using ghc --make ................................... 65 Expression evaluation mode ............................ 66 Batch compiler mode ................................. 66 6.1.6 Verbosity options .................................. 67 6.1.7 Platform-specific Flags ............................... 72 6.1.8 Miscellaneous flags ................................. 72 6.2 Warnings and sanity-checking ............................... 73 6.3 Optimisation (code improvement) ............................. 88 ii 6.3.1 -O*: convenient “packages” of optimisation flags. .............. 89 6.3.2 -f*: platform-independent flags ......................... 89 6.4 Using Concurrent Haskell ................................. 100 6.5 Using SMP parallelism ................................... 101 6.5.1 Compile-time options for SMP parallelism ................... 101 6.5.2 RTS options for SMP parallelism ......................... 102 6.5.3 Hints for using SMP parallelism ......................... 103 6.6 Flag reference ........................................ 103 6.6.1 Verbosity options .................................. 103 6.6.2 Alternative modes of operation .......................... 106 6.6.3 Which phases to run ................................ 107 6.6.4 Redirecting output ................................. 107 6.6.5 Keeping intermediate files ............................. 108 6.6.6 Temporary files .................................... 109 6.6.7 Finding imports ................................... 109 6.6.8 Interface file options ................................ 109 6.6.9 Recompilation checking .............................. 109 6.6.10 Interactive-mode options .............................. 110 6.6.11 Packages ....................................... 111 6.6.12 Language options .................................. 112 6.6.13 Warnings ....................................... 112 6.6.14 Optimisation levels ................................. 119 6.6.15 Individual optimisations .............................. 119 6.6.16 Profiling options ................................... 125 6.6.17 Program coverage options ............................. 125 6.6.18 C pre-processor options .............................. 126 6.6.19 Code generation options .............................. 126 6.6.20 Linking options .................................... 127 6.6.21 Plugin options .................................... 129 6.6.22 Replacing phases .................................. 129 6.6.23 Forcing options to particular phases ....................... 130 6.6.24 Platform-specific options .............................. 130 6.6.25 Compiler debugging options ............................ 130 6.6.26 Miscellaneous compiler options .......................... 135 6.7 Running a compiled program ............................... 135 6.7.1 Setting RTS options ................................. 135 Setting RTS options on the command line .................... 136 Setting RTS options at compile time ........................ 136 Setting RTS options with the GHCRTS environment variable .......... 137 “Hooks” to change RTS behaviour ......................... 137 6.7.2 Miscellaneous RTS options ............................ 138 6.7.3 RTS options to control the garbage collector .................. 139 6.7.4 RTS options to produce runtime statistics ................... 145 6.7.5 RTS options for concurrency and parallelism ................. 147 6.7.6 RTS options for profiling .............................. 148 6.7.7 Tracing ........................................ 148 6.7.8 RTS options for hackers, debuggers, and over-interested souls ...... 149 6.7.9 Getting information about the RTS ........................ 151 6.8 Filenames and separate compilation ........................... 152 6.8.1 Haskell source files ................................. 152 6.8.2 Output files ...................................... 152 6.8.3 The search path ................................... 153 6.8.4 Redirecting the compilation output(s) ...................... 154 6.8.5 Keeping Intermediate Files ............................ 156 iii 6.8.6 Redirecting temporary files ............................ 156 6.8.7 Other options related to interface files ..................... 156 6.8.8 Options related to extended interface files ................... 157 6.8.9 The recompilation checker ............................. 157 6.8.10 How to compile mutually recursive modules .................. 158 6.8.11 Module signatures .................................. 160 6.8.12 Using make .....................................