Changes between Version 1 and Version 2 of NewPlugins


Ignore:
Timestamp:
Jan 17, 2011 3:52:19 PM (3 years ago)
Author:
thoughtpolice
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • NewPlugins

    v1 v2  
    2727=== Basic overview of the plugins API for Core === 
    2828 
    29 TODO 
     29Modules can be loaded by GHC as compiler plugins by exposing a declaration called 'plugin' of type 'GHCPlugins.Plugin', which is an ADT containing a function that installs a pass into the Core pipeline. 
     30 
     31{{{ 
     32module Some.Plugin.Module (plugin) where 
     33import GHCPlugins 
     34 
     35plugin :: Plugin 
     36plugin = defaultPlugin { 
     37  installCoreToDos = install 
     38} 
     39 
     40 
     41-- type CommandLineOption = String 
     42 
     43install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo] 
     44install _options passes = do 
     45  ... 
     46 
     47 
     48}}} 
     49 
     50We can think of `CoreToDo` as being a type synonym for `(Core -> Core)` - that is, an installation function inserts a pass into the list of core passes by just inserting itself into the list and returning it. For example, the CSE pass actually couples a simplification pass, followed by CSE into the front of the compilation pipeline: 
     51 
     52{{{ 
     53module CSE.Plugin where 
     54 
     55... 
     56 
     57install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo] 
     58install _options todos = do 
     59    -- You should probably run this with -fno-cse ! 
     60    return $ CoreDoPasses [defaultGentleSimplToDo, cse_pass] : todos 
     61 
     62cse_pass = CoreDoPluginPass "Plugged-in common sub-expression" (BindsToBindsPluginPass cseProgram) 
     63}}} 
     64 
     65More specifically, a `CoreToDo` describes some sort of particular pass over a Core program that can be invoked as many times as you like. For reference, `defaultGentlSimplToDo` is constructed using `CoreDoSimplify`. In this case, we construct a `CoreDoPluginsPass`, which takes a name and a `PluginPass` which looks like the following: 
     66 
     67{{{ 
     68data PluginPass = BindsToBindsPluginPass ([CoreBind] -> CoreM [CoreBind]) -- ^ Simple pass just mutating the Core bindings 
     69                | ModGutsToBindsPluginPass (ModGuts -> CoreM [CoreBind])  -- ^ Pass that has access to the information from a 'ModGuts' 
     70                                                                          -- from which to generate it's bindings 
     71                | ModGutsToModGutsPluginPass (ModGuts -> CoreM ModGuts)   -- ^ Pass that can change everything about the module being compiled. 
     72                                                                          -- Do not change any field other than 'HscTypes.mg_binds' unless you 
     73                                                                          -- know what you're doing! Plugins using this are unlikely to be stable 
     74                                                                          -- between GHC versions 
     75}}} 
     76 
     77Most people will be using the first case - that is, writing a `BindsToBindsPluginPass` that just manipulates every individual Core binding. 
    3078 
    3179= The Future =