Changes between Version 6 and Version 7 of Commentary/Compiler/API


Ignore:
Timestamp:
Sep 11, 2006 12:11:32 PM (8 years ago)
Author:
simonmar
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Commentary/Compiler/API

    v6 v7  
    44 
    55This section of the commentary describes everything between [wiki:Commentary/Compiler/HscMain HscMain] and the front-end; that is, the parts of GHC that coordinate the compilation of multiple modules. 
    6  
    7 == Orgainsation of the top of GHC == 
    8  
    9 [[Image(ghc-top.png)]] 
    10  
    11 The GHC API is the interface exported by [[GhcFile(compiler/main/GHC.hs)]].  To compile a Haskell module that uses the GHC API, use the flag {{{-package ghc}}} (in GHC 6.6 and later).  GHC itself contains a few front-ends: 
    12  
    13  * The "one-shot" mode, where GHC compiles each file on the command line separately (eg. {{{ghc -c Foo.hs}}}).  This mode 
    14    is implemented directly on top of [wiki:Commentary/Compiler/HscMain HscMain], since it compiles only one file at a 
    15    time.  In fact, this is all that GHC consisted of prior to version 5.00 when GHCi and {{{--make}}} were introduced. 
    16  
    17  * GHCi, the interactive environment, is implemented in [[GhcFile(compiler/ghci/InteractiveUI.hs)]] and sits squarely on top 
    18    of the GHC API. 
    19  
    20  * {{{--make}}} is almost a trivial client of the GHC API, and is implemented in [[GhcFile(compiler/main/Main.hs)]]. 
    21  
    22  * {{{-M}}}, the Makefile dependency generator, is also a client of the GHC API and is implemented in  
    23    [[GhcFile(compiler/main/DriverMkDepend.hs)]]. 
    24  
    25 Note that since GHC is packaged as a single binary, all of these front-ends are present, and there is a single command-line interface implemented in [[GhcFile(compiler/main/Main.hs)]]. 
    26  
    27  
    28 == The GHC API == 
    296 
    307The GHC API is rather stateful; the state of an interaction with GHC is stored in an abstract value of type {{{GHC.Session}}}.  The only fundamental reason for this choice is that the {{{Session}}} models the state of the RTS's linker, which must be single-threaded. 
     
    4118 * Load (compile) the source files: {{{load}}} 
    4219 
    43 === Targets === 
     20== Targets == 
    4421 
    4522The targets specify the source files or modules at the top of the dependency tree.  For a Haskell program there is often just a single target {{{Main.hs}}}, but for a library the targets would consist of every visible module in the library. 
     
    4724The {{{Target}}} type is defined in [[GhcFile(compiler/main/HscTypes.lhs)]].  Note that a {{{Target}}} includes not just the file or module name, but also optionally the complete source text of the module as a {{{StringBuffer}}}: this is to support an interactive development environment where the source file is being edited, and the in-memory copy of the source file is to be used in preference to the version on disk. 
    4825 
    49 === Dependency Analysis === 
     26== Dependency Analysis == 
    5027 
    5128The dependency analysis phase determines all the Haskell source files that are to be compiled or loaded in the current session, by traversing the transitive dependencies of the targets.  This process is called the ''downsweep'' because we are traversing the dependency tree downwards from the targets.  (The ''upsweep'', where we compile all these files happens in the opposite direction of course). 
     
    5330The {{{downsweep}}} function takes the targets and returns a list of {{{ModSummary}}} consisting of all the modules to be compiled/loaded. 
    5431 
    55 === The !ModSummary type === 
     32== The !ModSummary type == 
    5633 
    5734A {{{ModSummary}}} (defined in [[GhcFile(compiler/main/HscTypes.h)]]) contains various information about a module: 
     
    6744Converting a given module name into a {{{ModSummary}}} is done by {{{summariseModule}}} in [[GhcFile(compiler/main/GHC.hs)]].  Similarly, if we have a filename rather than a module name, we generate a {{{ModSummary}}} using {{{summariseFile}}}. 
    6845 
    69 === Loading (compiling) the Modules === 
     46== Loading (compiling) the Modules == 
    7047 
    7148When the dependency analysis is complete, we can load these modules by calling {{{GHC.load}}}.  The same interface is used regardless of whether we are loading modules into GHCi with the {{{:load}}} command, or compiling a program with {{{ghc --make}}}: we always end up calling {{{GHC.load}}}. 
     
    8764   modules for which no dependencies have changed. 
    8865 
    89 === Stable Modules === 
     66== Stable Modules == 
    9067 
    9168ToDo.