View source for Upgrading packages/Updating to GHC 6.10

A list of things that need updating when porting packages to newer library/cabal versions.

If you maintain a Haskell package this is for you.
For older versions of this document:

* [[/Updating to GHC 6.8]]

'''Updating to GHC 6.10 and Cabal 1.6'''

When upgrading to GHC 6.10, any of your packages that worked against
the base-3 library will continue to work (unless you define instances of the <code>Arrow</code> class: see below). GHC 6.10 provides both the old
base-3 library and the new base-4.

To ensure your old code continues to work, you can have the code compile
and link against base-3, and then, over time, migrate code to the base-4
series.

== Adding base-3 constraints ==

How to do this depends on how you build your Haskell code. We'll start
with the most simplistic build mechanisms. cabal-install, the most
sophisticated tool, will sort this all out for you anyway, so things
should change.

=== ghc --make ===

Force use of package base-3 when using --make,

    ghc --make -package base-3.0.3.0

===runhaskell ===

If you build your packages with the 'runhaskell Setup.hs configure'
method, then you can force the use of base-3,

    --constraint="base<4"

=== cabal-install===

It is worth upgrading cabal-install immediately (maybe before installing
GHC). This way you can use the smart dependency solver to work out what
to install for you.

 * install [http://hackage.haskell.org/cgi-bin/hackage-scripts/package/HTTP HTTP] from hackage
 * install [http://hackage.haskell.org/cgi-bin/hackage-scripts/package/zlib zlib] from hackage

Then build cabal-install.

You can also override the dependencies when using the 'cabal' binary, with

    --constraint="base<4"

== Typical breakages with GHC 6.10 ==

[http://article.gmane.org/gmane.comp.lang.haskell.glasgow.user/15430 48 new packages] break with the current GHC 6.10 release candidate.

The primary reasons are:

* Changes to the Arrow class definition break Arrow instances
* Changes to the return types of Map and Set functions
* Cabal changes
* Changes to ghc-api
* Changes to when 'forall' is parsed
* GHC.Prim was moved,
* Changes to -fvia-C and headers
* GADT changes,
* pragma warnings tightened
* Integer constructors have moved
* New warnings and used -Werror

Each of these has a standard way to solve the problem. Techniques should be attached here.

=== Arrow instances ===

The relevant change is essentially that Arrow became a subclass of Category. To be exact:

* <code>(.)</code> is a new function, in Category. <code>(>>>)</code> was removed from Arrow and made a function.
* <code>id</code> is a new function, in Category

The base-3 compatibility package contains the same classes as base-4, so it will not save you if you define instances of the Arrow class: you'll need to change your code.
Whenever you define an instance of Arrow you must also define an instance of Category, as follows:

* Add the following imports:
<haskell>
    import Control.Category
    import Prelude hiding (id,(.)) -- conflicts with Category otherwise
</haskell>
* Add <code>instance Category [your type] where</code> for any Arrow instances you define.
* Move your <code>(>>>)</code> definition into Category, and change <code>f >>> g = ...</code> into <code>g . f = ...</code>
* Define <code>id</code> in Category. The simplest definition is
<haskell>
    id = arr id
</haskell>
:but you may wish to manually specialize this for efficiency.

And you're done.

===Return types of Map and Set functions ===

Functions with signatures like
<haskell>
lookup :: (Monad m, Ord k) => k -> Map k a -> m a
</haskell>
have been specialized to
<haskell>
lookup :: (Ord k) => k -> Map k a -> Maybe a
</haskell>
If you assume the more specific type, your code will work with both old and new versions of the <code>containers</code> package.
The brute force approach is to change each <code>lookup k m</code> to
<haskell>
fromMaybe (fail "lookup: key not found") $
  lookup k m
</haskell>
but you could also consider how you want to handle possible failures, or at least give a more informative error message. 

=== Exception handling changes ===

The exception system was generalised in GHC 6.10, but GHC 6.10 still provides base-3, so all your applications can continue to work. 

Follow the steps for compiling against base-3 at the top of the page, based on your build system.

Note that if you use cabal-install, it is smart enough to work this out for you.

=== Changes to -fvia-C and headers ===

GHC 6.10 no longer includes extra header files when compiling with -fvia-C. This makes compilation with -fvia-C consistent with the native code generator.

As a consequence, defining inline functions in header files and relying on -fvia-C to pick them up no longer works.

* If you use a library that provides inline functions that you want to use, you will have to create wrapper functions to use them via FFI.
* If you use the <code>#def</code> feature of hsc2hs, you can no longer define inline functions. That is, replace <code>#def inline void foobar() { ... } </code> by just <code>#def void foobar() { ... }</code>

The problem typically manifests itself as link errors (for example "ghc26356_0.hc:(.text+0x20282): undefined reference to `hs_curses_color_pair'"). 

Beware: In some cases, a library using inline functions will be built successfully, but programs using the library will fail to build.

=== Changes to GADT matching ===

GHC now enforces the rule that in a GADT pattern match:

* the type of the scrutinee must be rigid
* the result type must be rigid
* the type of any variable free in the case branch must be rigid

Here "rigid" means "fully known to the compiler, usually by way of a type signature".  This rule is to make type inference simple and predictable.

Observe that this means that GHC must know the result type of the match ''at the match point''. There is no workaround other than finding a way to provide enough annotations in order to make GHC happy. Nevertheless, this heuristic was suggested:

<blockquote>My general method for solving these problems was to find an expression
or statement that enclosed both the left and right hand sides, and add
<code>:: Int</code> to it. I then recompiled and got an error message saying it
couldn't match <code>Int</code> with "something". I then replaced <code>Int</code> with
"something" and it worked.</blockquote>

In any case, [http://thread.gmane.org/gmane.comp.lang.haskell.glasgow.user/15153 this thread] is probably a must-read if you are running into this.

== Backwards compatibility ==

The new, suggested Cabal version range syntax,

   build-depends: base-3.*

is not backwards compatible with older versions of Cabal. Users will need to upgrade to the newer Cabal to build packages that start using this syntax.

== GHC API changes ==

For converting a package that uses GHC-API, see [[http://hackage.haskell.org/trac/ghc/wiki/GhcApiStatus GhcApiStatus]] for notes on the changes to the API and its use in 6.10. There are four main changes:

* add imports '<code>MonadUtils</code>' and '<code>SrcLoc</code>'
* use of '<code>runGhc</code>' instead of newSession
* code using getSession and related, converts to become monadic within <code>Ghc</code>monad
* String type becomes Located String type. To convert basic strings, use "L noSrcSpan <string>"

[[Category:Libraries]]