Difference between revisions of "Upgrading packages/Updating to GHC 6.10"
RossPaterson (talk | contribs) (example of error message) |
DuncanCoutts (talk | contribs) (Reorder and extend content) |
||
Line 1: | Line 1: | ||
− | A list of things that need updating when porting packages to newer |
+ | A list of things that need updating when porting packages to newer library/cabal versions. |
+ | |||
− | library/cabal versions. |
||
+ | If you maintain a Haskell package this is for you. |
||
== Updating to GHC 6.8 and Cabal 1.2 == |
== Updating to GHC 6.8 and Cabal 1.2 == |
||
+ | |||
+ | So now that GHC 6.8.x is out you'll want to test your package with it. We'd especially like maintainers of packages that are distributed on http://hackage.haskell.org/ to test their packages and update them as necessary. |
||
+ | However everyone would appreciate it if your packages will still work with GHC |
||
+ | 6.6.x, so read below for details on how to do that. |
||
+ | |||
⚫ | |||
+ | |||
+ | You'll most likely find that your package fails to build with GHC 6.8.x |
||
+ | with an error message like this: |
||
+ | |||
+ | <pre> |
||
+ | Could not find module `Data.Map': it is a member of package |
||
+ | containers-0.1.0.0, which is hidden. |
||
+ | </pre> |
||
+ | |||
+ | This is the first symptom of the change in the base library in GHC 6.8.x. Several parts of the old base library got split out into separate packages. For example Data.Map is now in the containers package (see below for the complete list of [[#New core libraries]]). Unfortunately this means most packages need updating. |
||
=== Cabal configuration support === |
=== Cabal configuration support === |
||
+ | |||
+ | Of course you'd also like to make your packages continue to work with |
||
+ | GHC 6.6.x (and perhaps older). If you go and just add <hask>containers</hask> to your package's <hask>build-depends</hask> then it will no longer work with GHC 6.6.x or older. So the solution at the moment is to use Cabal configurations like so: |
||
+ | |||
+ | <pre> |
||
⚫ | |||
⚫ | |||
⚫ | |||
⚫ | |||
⚫ | |||
⚫ | |||
+ | build-depends: base < 3 |
||
+ | </pre> |
||
+ | |||
+ | Since this uses a new Cabal feature you'll have to make your packages |
||
+ | require Cabal 1.2 or later: |
||
+ | |||
+ | <pre>cabal-version: >=1.2</pre> |
||
+ | |||
+ | This is ok since Cabal 1.2.x comes with GHC 6.8.x and can also be installed from [http://hackage.haskell.org/cgi-bin/hackage-scripts/package/Cabal hackage] for older GHC versions. |
||
+ | |||
⚫ | |||
+ | |||
+ | The new Cabal syntax is explained in the [http://haskell.org/cabal/release/rc/doc/users-guide/x30.html#configurations Cabal user guide] |
||
=== Cabal API changes === |
=== Cabal API changes === |
||
− | Many packages that use non-default Setup.hs or Setup.lhs files need to be updated as they use Cabal APIs that have changed. In many cases new features in Cabal |
+ | Many packages that use non-default <hask>Setup.hs</hask> or <hask>Setup.lhs</hask> files need to be updated as they use Cabal APIs that have changed. In many cases new features in Cabal 1.2 allow these packages to go back to using the default <hask>Setup.hs</hask>. |
A more detailed survey of the packages from the [http://hackage.haskell.org hackage] collection is here: |
A more detailed survey of the packages from the [http://hackage.haskell.org hackage] collection is here: |
||
http://www.haskell.org/pipermail/libraries/2007-September/008265.html |
http://www.haskell.org/pipermail/libraries/2007-September/008265.html |
||
+ | If your package does use the default <hask>Setup.hs</hask> file then you can indicate this by adding the following line to your <hask>.cabal</hask> file: |
||
⚫ | |||
+ | |||
+ | <pre>build-type: Simple</pre> |
||
+ | |||
+ | This allows tools like <pre>cabal-install</pre> to avoid compiling the Setup.hs file at all. The other build types are explained in the [http://haskell.org/cabal/release/rc/doc/users-guide/x30.html#general-fields Cabal user guide]. |
||
+ | |||
+ | === New core libraries === |
||
The base package was split up, and new dependencies are now required; |
The base package was split up, and new dependencies are now required; |
||
Line 30: | Line 77: | ||
([http://www.haskell.org/haskellwiki/Image:Boot-packages.png dependency graph of the boot libraries]) |
([http://www.haskell.org/haskellwiki/Image:Boot-packages.png dependency graph of the boot libraries]) |
||
− | These boot packages are included with |
+ | These boot packages are included with GHC 6.8.x. If your package imports any of these modules, you need only add the corresponding packages to the <hask>build-depends</hask> line in your cabal file. |
For example, the GHC error message |
For example, the GHC error message |
||
<pre> |
<pre> |
||
Line 36: | Line 83: | ||
it is a member of package directory-1.0.0.0, which is hidden |
it is a member of package directory-1.0.0.0, which is hidden |
||
</pre> |
</pre> |
||
− | indicates that < |
+ | indicates that <pre>directory</pre> should be added to the ''build-depends'' line. |
− | |||
− | However if you want to support both ghc-6.6 and ghc-6.8 you need to use the configurations feature in your .cabal file. For example: |
||
− | |||
⚫ | |||
⚫ | |||
− | |||
⚫ | |||
⚫ | |||
− | build-depends: base >= 3, pretty, directory, old-time, process, containers |
||
⚫ | |||
⚫ | |||
− | |||
⚫ | |||
=== Data.ByteString api changes === |
=== Data.ByteString api changes === |
||
Line 56: | Line 90: | ||
<haskell>packCStringLen :: Foreign.C.String.CStringLen -> ByteString</haskell> |
<haskell>packCStringLen :: Foreign.C.String.CStringLen -> ByteString</haskell> |
||
to |
to |
||
− | <haskell>packCStringLen :: Foreign.C.String.CStringLen -> IO ByteString</haskell> |
+ | <haskell>packCStringLen :: Foreign.C.String.CStringLen -> IO ByteString</haskell> |
− | module Data.ByteString.Base has been split into two. The "unsafe" functions moved to Data.ByteString.Unsafe and the others moved into Data.ByteString.Internal. The stable API going forward is all the modules exposed by the bytestring package except for the .Internal modules and the .Fusion module. |
+ | <hask>module Data.ByteString.Base</hask> has been split into two. The "unsafe" functions moved to <hask>Data.ByteString.Unsafe</hask> and the others moved into <hask>Data.ByteString.Internal</hask>. The stable API going forward is all the modules exposed by the <hask>bytestring</hask> package except for the <hask>.Internal</hask> modules and the <hask>.Fusion</hask> module. |
The lazy bytestring representation type has changed. Instead of a newtyped list: |
The lazy bytestring representation type has changed. Instead of a newtyped list: |
||
Line 66: | Line 100: | ||
The crucial difference is that in the latter representation we can unpack the strict bytestring into the <hask>Chunk</hask> constructor which reduces the number of indirections to get at the string data from two to one. |
The crucial difference is that in the latter representation we can unpack the strict bytestring into the <hask>Chunk</hask> constructor which reduces the number of indirections to get at the string data from two to one. |
||
+ | |||
+ | === Other core library api changes === |
||
+ | |||
+ | They are listed in detail in the [http://haskell.org/ghc/docs/latest/html/users_guide/release-6-8-1.html#id3129818 GHC 6.8 release notes] |
Revision as of 01:14, 1 December 2007
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.
Updating to GHC 6.8 and Cabal 1.2
So now that GHC 6.8.x is out you'll want to test your package with it. We'd especially like maintainers of packages that are distributed on http://hackage.haskell.org/ to test their packages and update them as necessary. However everyone would appreciate it if your packages will still work with GHC 6.6.x, so read below for details on how to do that.
base package split up
You'll most likely find that your package fails to build with GHC 6.8.x with an error message like this:
Could not find module `Data.Map': it is a member of package containers-0.1.0.0, which is hidden.
This is the first symptom of the change in the base library in GHC 6.8.x. Several parts of the old base library got split out into separate packages. For example Data.Map is now in the containers package (see below for the complete list of #New core libraries). Unfortunately this means most packages need updating.
Cabal configuration support
Of course you'd also like to make your packages continue to work with
GHC 6.6.x (and perhaps older). If you go and just add containers
to your package's build-depends
then it will no longer work with GHC 6.6.x or older. So the solution at the moment is to use Cabal configurations like so:
flag splitBase description: Choose the new smaller, split-up base package. library if flag(splitBase) build-depends: base >= 3, containers else build-depends: base < 3
Since this uses a new Cabal feature you'll have to make your packages require Cabal 1.2 or later:
cabal-version: >=1.2
This is ok since Cabal 1.2.x comes with GHC 6.8.x and can also be installed from hackage for older GHC versions.
For a bigger example see Cabal's own .cabal file
The new Cabal syntax is explained in the Cabal user guide
Cabal API changes
Many packages that use non-default Setup.hs
or Setup.lhs
files need to be updated as they use Cabal APIs that have changed. In many cases new features in Cabal 1.2 allow these packages to go back to using the default Setup.hs
.
A more detailed survey of the packages from the hackage collection is here: http://www.haskell.org/pipermail/libraries/2007-September/008265.html
If your package does use the default Setup.hs
file then you can indicate this by adding the following line to your .cabal
file:
build-type: Simple
This allows tools like
cabal-install
to avoid compiling the Setup.hs file at all. The other build types are explained in the Cabal user guide.
New core libraries
The base package was split up, and new dependencies are now required;
- array: Data.Array and below
- bytestring: Data.ByteString and below
- packedstring: Data.PackedString (deprecated)
- containers: Data.{Graph,IntMap,IntSet,Map,Sequence,Set,Tree}
- random: System.Random
- pretty: Text.PrettyPrint and below
- process: System.Cmd, System.Process and below
- directory: System.Directory
- old-time: System.Time
- old-locale: System.Locale
(dependency graph of the boot libraries)
These boot packages are included with GHC 6.8.x. If your package imports any of these modules, you need only add the corresponding packages to the build-depends
line in your cabal file.
For example, the GHC error message
Could not find module `System.Directory': it is a member of package directory-1.0.0.0, which is hidden
indicates that
directory
should be added to the build-depends line.
Data.ByteString api changes
Data.ByteString.packCStringLen is no longer a pure function; its signature has changed from
packCStringLen :: Foreign.C.String.CStringLen -> ByteString
to
packCStringLen :: Foreign.C.String.CStringLen -> IO ByteString
module Data.ByteString.Base
has been split into two. The "unsafe" functions moved to Data.ByteString.Unsafe
and the others moved into Data.ByteString.Internal
. The stable API going forward is all the modules exposed by the bytestring
package except for the .Internal
modules and the .Fusion
module.
The lazy bytestring representation type has changed. Instead of a newtyped list:
newtype ByteString = LPS [Strict.ByteString]
it is now:
data ByteString = Empty | Chunk !Strict.ByteString ByteString
The crucial difference is that in the latter representation we can unpack the strict bytestring into the Chunk
constructor which reduces the number of indirections to get at the string data from two to one.
Other core library api changes
They are listed in detail in the GHC 6.8 release notes