breaking Haskell circular imports with C preprocessor (cpp)

This article shows how to solve the “circular imports” problem in Haskell, using the C preprocessor, in a swift way. If you are in a hurry, go to C preprocessor section and do not skip Caveats.

The problem

The difficulty is well known:

1. you start a new Haskell project. After a cup of coffee, with glee and hope you flesh your first data-types and functions:

   data Big = Big
   data Test = Test Big
   
   testFun :: Big -> Test
   testFun = undefined
   
   bigFun :: Test -> IO Big
   bigFun = undefined

2. after a while the initial module is getting bigger and bigger, so you decide it would be a good idea to split it in manageable pieces:

   -- A.hs
   module A where
   
   data Big = Big
   bigFun :: Test -> IO Big
   bigFun = undefined
   
   -- B.hs
   module B where
   
   data Test = Test deriving (Show)
   testFun :: Big -> Test
   testFun = undefined

3. you eagerly run cabal new-build, but GHC complains:

   Module imports form a cycle:
            module ‘B’ (src/B.hs)
           imports ‘A’ (src/A.hs)
     which imports ‘B’ (src/B.hs)

   “Lord, why me?!”

Existing solutions

There are three accepted ways of dealing with circular imports:

• putting every datatype in a big Types.hs module: this is quick, but now your data is away from your functions, making any edit action a chore. “Types-sink” modules will grow themselves very big, very fast!

• using type parameters (as explained in the HaskellWiki): my gripe with type parameters is that with nested structures you might end up having top types with a lot of parameters.

  Moreover adding parameters when the structure is not parametric makes reading the code a chore. Which one would you rather go through, this:

  data Game r q m b = Game r q m b

  or this?

  data Game = Game Room Quarterstaff Magic Book

• using hs-boot (explained in the GHC manual): hs-boot files are like “signature files”, you put in there the minimal information to allow a successful compilation, e.g.:

  -- B.hs-boot
  
  module B where
  data Test

  Importing B like this

  import {-# SOURCE #-} B

  will solve the import problem.

  hs-boot forces you to modify two files for each change to the code; deciding where to “break the cycle” can become a not-so-trivial decision when using it on an already big codebase.

  Check this repository to see a cabalised example.

C preprocessor

What I am proposing here is a quick hack that uses the C preprocessor (cpp) to break circular imports. Download the working example and let us see what it is all about. We will start from file A.hs:

module A where

#define beta
#include "B.hs"

data Big = Big

bigFun :: Test -> IO Big
bigFun = undefined

We do not import B via import B, but using #include. Note the #define beta before it. Examining B.hs will reveal the trick:

#ifdef beta
-- data declaration
data Test = Test Big
#undef beta

#elif 1
-- your module
module B where

import A

someFun :: Big -> Test
someFun = undefined
#endif

Data declaration is sandwiched between #ifdef beta and #undef beta, while the rest of the module goes between #elif 1 and #endif.

It is not difficult to see the preprocessor executes two passes: one to transfer data-types to A.hs (via CPP), the second to allow the rest of B.hs to be compiled by GHC. The benefits of this approach are:

• Your types are where they belong to: on top of their module, near the functions used to modify/use/transform them. No Types.hs sink-module with everything in it.
• GHC is smart enough to output meaningful line-number errors: if you mangle the definition of data Test, the compiler will point at file B.hs, line 3.
• No need to add parameters to your concrete types, or to add a signature file, or any kind of duplication bar the initial scaffolding.
• B.hs is an actual Haskell file, so you are not losing syntax-highlight.
• The solution is quick and implemented with little pain.

I advise to add a ghc-options: -XCPP in your .cabal file, otherwise you are forced to put a {#- Language CPP -#} on top of every module.

Caveats

I tested this solution in real life, these are the warnings:

• Since most of your modules will import module A, writing meaningful qualified imports on types gets difficult (thanks to Massimo Zaniboni for pointing this to me).
• If you use Template Haskell, remember that order matters: put every makeLenses and similar after your data imports/declarations in A.hs.
• Tools like ghcid (reload on save) are not fond of C preprocessor. You might need to restart them after tweaking CPP; if that is unacceptable, add :set -DSTAGE=2 to your local .ghci config file.
• If you can, consider using cpphs, as it is slightly better behaved than plain CPP in corner cases (e.g. multiline strings).

Conclusion

If you need a quick fix to mutually recursive modules in Haskell, using CPP is an option that can save you headaches. Hopefully the problem will soon be addressed at compiler level.