Changes between Version 1 and Version 2 of NewPlugins


Ignore:
Timestamp:
Jan 17, 2011 3:52:19 PM (5 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 =