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.