GHC Plugs Out
=============
Type checker plugins without the type checking.
|cabal-ci|
Introduction
------------
When getting ready to launch, one of the steps is the plugs-out test. Can the
spacecraft function on its own without power or fuel from all cables and
umbilicals?
When debugging GHC plugins, I've added tracing and changed the wiring. Rather
than throw those edits away, I've collected them in `ghc-plugs-out`_, a package
of tests that don't supply any power or fuel for typechecking. It is the first
multiple library package I've put together [#]_.
Wiring Diagram
--------------
Here's a type checker plugin that doesn't do any solving but instead writes its
call count.
.. code-block:: haskell
{-# LANGUAGE QuasiQuotes, NamedFieldPuns #-}
module CallCount.TcPlugin (callCount) where
import Language.Haskell.Printf (s)
import Data.IORef (IORef)
import IOEnv (newMutVar, readMutVar, writeMutVar)
import TcPluginM (tcPluginIO)
import TcRnTypes (TcPluginResult(..), TcPlugin(..), unsafeTcPluginTcM)
newtype State = State { callref :: IORef Int }
callCount :: TcPlugin
callCount =
TcPlugin
{ tcPluginInit = return . State =<< (unsafeTcPluginTcM $ newMutVar 1)
, tcPluginSolve = \State{callref = c} _ _ _ -> do
n <- unsafeTcPluginTcM $ readMutVar c
tcPluginIO . putStrLn $ [s|>>> GHC-TcPlugin #%d|] n
unsafeTcPluginTcM $ writeMutVar c (n + 1)
return $ TcPluginOk [] []
, tcPluginStop = const $ return ()
}
Plugins are flagged for recompilation in their ``pluginRecompile`` field.
Let's now wire up and test the pure ``CallCount.Pure.Plugin`` and the impure
``CallCount.Impure.Plugin``. The recommended way to wire up a plugin is with
a pragma, only in source files that need the plugin.
.. code-block:: haskell
{-# OPTIONS_GHC -fplugin CallCount.Pure.Plugin #-}
module Main where
main :: IO a
main = undefined
The call count prints on first build but not when there's no work to do.
.. code-block:: pre
> cabal build test-wireup-pure-by-pragma
[1 of 1] Compiling Main
>>> GHC-TcPlugin #1
> cabal build test-wireup-pure-by-pragma
Up to date
A plugin can also be wired up with an option, say in a cabal file. This is
probably fine if all your modules need a plugin.
.. code-block:: yaml
test-suite test-wireup-pure-by-option
import: opts
type: exitcode-stdio-1.0
main-is: Main.hs
hs-source-dirs: test-suites/wireup-pure-by-option
ghc-options: -Wall -fplugin CallCount.Pure.Plugin
build-depends: base, call-count-plugin
.. code-block:: pre
> cabal build test-wireup-pure-by-option
[1 of 1] Compiling Main
>>> GHC-TcPlugin #1
If you mix and match both ways of doing the wiring you'll end up with two
instances of the plugin in the compilation.
.. code-block:: pre
> cabal build test-wireup-pure-by-both
[1 of 1] Compiling Main
>>> GHC-TcPlugin #1
>>> GHC-TcPlugin #1
If your plugin is impure, it's going to force a recompilation.
.. code-block:: pre
> cabal build test-wireup-impure-by-pragma
[1 of 1] Compiling Main
>>> GHC-TcPlugin #1
[1 of 1] Compiling Main [Impure plugin forced recompilation]
>>> GHC-TcPlugin #1
> cabal build test-wireup-impure-by-option
[1 of 1] Compiling Main
>>> GHC-TcPlugin #1
[1 of 1] Compiling Main [Impure plugin forced recompilation]
>>> GHC-TcPlugin #1
> cabal build test-wireup-impure-by-both
[1 of 1] Compiling Main
>>> GHC-TcPlugin #1
>>> GHC-TcPlugin #1
[1 of 1] Compiling Main [Impure plugin forced recompilation]
>>> GHC-TcPlugin #1
>>> GHC-TcPlugin #1
Modularity
----------
GHC compiles modules. We see the counter plugin is called on twice when
functions ``foo`` and ``bar`` are in module ``Main``.
.. code-block:: haskell
{-# OPTIONS_GHC -fplugin CallCount.Pure.Plugin #-}
module Main where
foo :: IO a
foo = undefined
bar :: IO a
bar = undefined
main :: IO ()
main = return ()
.. code-block:: pre
> cabal build test-counter-main
[1 of 1] Compiling Main
>>> GHC-TcPlugin #1
>>> GHC-TcPlugin #2
Moving ``foo`` and ``bar`` to module ``FooBar`` and the counter plugin reports
two calls again.
.. code-block:: pre
> cabal build test-counter-foobar-main
[1 of 2] Compiling FooBar
>>> GHC-TcPlugin #1
>>> GHC-TcPlugin #2
[2 of 2] Compiling Main
Move these functions into separate modules and we count one call for each module.
.. code-block:: pre
> cabal build test-counter-foo-bar-main
[1 of 3] Compiling Bar
>>> GHC-TcPlugin #1
[2 of 3] Compiling Foo
>>> GHC-TcPlugin #1
[3 of 3] Compiling Main
Undefined is not a Function
---------------------------
If your plugin behaves badly it is going to hurt. GHC panics when any one of
the functions required of a type checker plugin is implemented undefined.
.. code-block:: haskell
plugin :: Plugin
plugin = mkPureTcPlugin undefSolve
undefSolve :: TcPlugin
undefSolve = noOp { tcPluginSolve = \_ _ _ _ -> undefined }
noOp :: TcPlugin
noOp =
TcPlugin
{ tcPluginInit = return ()
, tcPluginSolve = \_ _ _ _ -> return $ TcPluginOk [] []
, tcPluginStop = const $ return ()
}
mkPureTcPlugin :: TcPlugin -> Plugin
mkPureTcPlugin p =
defaultPlugin
{ tcPlugin = const $ Just p
, pluginRecompile = purePlugin
}
.. code-block:: pre
> cabal build test-undefined-solve
[1 of 1] Compiling Undefined.Solve.Plugin
[1 of 1] Compiling Main
ghc: panic! (the 'impossible' happened)
Please report this as a GHC bug: http://www.haskell.org/ghc/reportabug
I would have liked to use record update syntax for undefSolve as shown above
but this is not yet possible [#]_ with GHC when the data type has an
existential qualifier and that is how TcPlugin is defined [#]_.
.. code-block:: haskell
data TcPlugin = forall s. TcPlugin
{ tcPluginInit :: TcPluginM s
-- ^ Initialize plugin, when entering type-checker.
, tcPluginSolve :: s -> TcPluginSolver
-- ^ Solve some constraints.
-- TODO: WRITE MORE DETAILS ON HOW THIS WORKS.
, tcPluginStop :: s -> TcPluginM ()
-- ^ Clean up after the plugin, when exiting the type-checker.
}
Care Free
---------
Type checker plugins are of course called on by GHC to resolve constraints.
Some need solving and others don't. GHC knows that it can get an ``a`` from
``undefined`` but maybe a plugin can do better so we get called.
.. code-block:: haskell
{-# OPTIONS_GHC -fplugin Undefined.Solve.Plugin #-}
module Main where
main :: IO a
main = undefined
Going from ``()`` to ``()`` needs no further resolution. GHC can handle this
by itself. The ``test-undefined-*-carefree`` test suites have these mains.
The ones without carefree in their name don't. They have the ``a`` from
``undefined`` mains.
.. code-block:: haskell
{-# OPTIONS_GHC -fplugin Undefined.Solve.Plugin #-}
module Main where
main :: IO ()
main = return ()
So we've seen that a typechecker plugin's solve function **may** be called but
its init and stop functions are **always** called.
.. code-block:: ascii
+-------------------------------+------------+
| Test Suite | GHC Panics |
+===============================+============+
| test-undefined-init | x |
+-------------------------------+------------+
| test-undefined-init-carefree | x |
+-------------------------------+------------+
| test-undefined-solve | x |
+-------------------------------+------------+
| test-undefined-solve-carefree | |
+-------------------------------+------------+
| test-undefined-stop | x |
+-------------------------------+------------+
| test-undefined-stop-carefree | x |
+-------------------------------+------------+
Takeaways
---------
* We should wire up type checker plugins with pragmas only in modules that need
it.
* Don't forget to flag pure plugins as such.
* If GHC doesn't need help resolving constraints then it won't call out to your plugin.
* Modules are the units of compilation.
License
-------
.. code-block:: ascii
Copyright © Phil de Joux 2017-2020
Copyright © Block Scope Limited 2017-2020
This software is subject to the terms of the Mozilla Public License, v2.0. If
a copy of the MPL was not distributed with this file, you can obtain one at
http://mozilla.org/MPL/2.0/.
.. _ghc-plugs-out: https://github.com/BlockScope/ghc-plugs-out
.. _ghc-2595: https://gitlab.haskell.org/ghc/ghc/issues/2595
.. _fgaz-GSoC-2018: https://fgaz.me/posts/2019-11-14-cabal-multiple-libraries/
.. [#] Multiple libraries were added to cabal 3.0, see fgaz-GSoC-2018_.
.. [#] The error if you try is "Record update for insufficiently polymorphic field", see ghc-2595_.
.. [#] These field haddock comments are verbatim from the GHC source.
.. |cabal-ci| image:: https://github.com/BlockScope/ghc-plugs-out/workflows/cabal/badge.svg