Changes between Version 18 and Version 19 of GhcApiStatus


Ignore:
Timestamp:
Aug 4, 2008 10:46:35 PM (7 years ago)
Author:
nominolo
Comment:

Describe current API design

Legend:

Unmodified
Added
Removed
Modified
  • GhcApiStatus

    v18 v19  
    22 
    33This Wiki page shall serve as a central place to collect all issues and ideas related to the GHC API.  If you feel that something is missing from this page, please add a comment to the comment section below. 
     4 
     5------- 
     6 
     7= Current GHC API design = 
     8 
     9Most exported API functions that were previously in {{{IO}}} are now 
     10in the {{{Ghc}}} monad.  Those functions now require no {{{Session}}} 
     11parameter.  To start a GHC API session you now use: 
     12 
     13{{{ 
     14withGhc :: Maybe FilePath  -- path to GHC library 
     15        -> Maybe [String]  -- ^ Optional list of static flags. 
     16        -> Ghc a           -- ^ The action(s) to perform. 
     17        -> IO a 
     18}}} 
     19 
     20The first parameter can be determined automatically with the ghc-path 
     21package.  The second is a set of "static" command line flags, for 
     22example, profiling options.  Having those part of the run function for 
     23the monad avoids complicated usage rules (e.g. before parseStaticFlags 
     24had to be called before {{{newSession}}}). 
     25 
     26{{{load}}} and {{{setTarget}}} work like before.  {{{checkModule}}} 
     27has been split up into: 
     28 
     29{{{ 
     30parseModule :: ModuleName -> Ghc ParsedModule 
     31typecheck :: ParsedModule -> Ghc TypecheckedModule 
     32desugarModule :: TypecheckedModule -> Ghc DesugaredModule 
     33loadModule :: TypecheckedMod m => m -> Ghc () 
     34}}} 
     35 
     36{{{TypecheckedMod}}} has two instances {{{TypecheckedModule}}}, 
     37{{{DesugaredModule}}}.  A {{{DesugaredModule}}} desugared module is a 
     38very similar to a {{{CoreModule}}}, but the latter contains less 
     39information, while the former also contains all the information from 
     40the parser and typechecker.  Users should therefore be careful about 
     41memory leaks by and discard old intermediate results as soon as 
     42possible. 
     43 
     44Compile errors are thrown inside the {{{Ghc}}} monad, and can be 
     45caught with {{{onCompileError}}}.  {{{IO}}} errors can also be caught 
     46using {{{ghcCatch}}}.  Warnings are logged automatically and can be 
     47retrieved using {{{getWarnings}}} or discarded using 
     48{{{clearWarnings}}}.  Error messages are communicated in the 
     49exceptions thrown. 
     50 
     51== Current Work == 
     52 
     53I am currently evaluating what information can be added to the output 
     54of the various phases and how hard it would be to modify or create 
     55intermediate types (e.g., typecheck a "hand-crafted" module). 
     56 
     57Additionally, logging of errors and warnings is somewhat spread-out, 
     58so I try to find the places where that happens and incorporate that 
     59into the {{{Ghc}}} monad. 
     60 
     61------ 
     62 
     63= Project Overview = 
    464 
    565Simon Marlow reported that the last time he tried to work on the GHC API, it turned into a huge refactoring task.  This could mean that it may take a while until bigger changes are visible and it is very likely that programs that currently use the GHC API will break.  Hopefully, though, it will lead to a more usable GHC API and maybe to a more hackable code base in general.