Skip to content

2.0 migration guide

Jump to bottom
Mikhail Glushenkov edited this page Sep 8, 2017 · 6 revisions

Cabal 2.0 comes with a number of backwards-compatibility breaking changes. This page documents some of them and gives advice on how to adjust your code for the new APIs. When possible, we will give guidance on how to write your code in a way that is simultaneously compatible with 2.0 and earlier versions, but in many cases you will have to use CPP to handle the differences.

cabal_macros.h

We now generate a macro file for each component which contains only information about the direct dependencies of that component. Consequently, dist/build/autogen/cabal_macros.h contains only the macros for the library, and is not generated if a package has no library; to find the macros for an executable named foobar, look in dist/build/foobar/autogen/cabal_macros.h. Similarly, if you used autogenModulesDir you should now use autogenComponentModulesDir, which now requires a ComponentLocalBuildInfo argument as well in order to disambiguate which component the autogenerated files are for.

Newly opaque data types

The following data types are now opaque (in order to support a more efficient underlying representation):

  • PackageName
  • ComponentId
  • FlagName
  • AbiHash
  • Version

To construct these types, use mkXXXXX; to destruct them, use unXXXXX (e.g., for PackageName that'll be mkPackageName/unPackageName). These types can also be converted back into strings using display, which is backwards compatible with old versions of Cabal.

Changed data types

  • GenericPackageDescription used to have fields condExecutables, condTestSuites and condBenchmarks of type [(String, CondTree ConfVar [Dependency] x)]. The String field is now has type UnqualComponentName.

  • TestSuite and Benchmark no longer have testEnabled and benchmarkEnabled. If you used enabledTests or enabledBenchmarks, please instead use enabledTestLBIs and enabledBenchLBIs (you will need a LocalBuildInfo for these functions.) Additionally, the semantics of withTest and withBench have changed: they now iterate over all buildable such components, regardless of whether or not they have been enabled; if you only want enabled components, use withTestLBI and withBenchLBI.

Changed functions

  • readPackageDescription (from Distribution.PackageDescription.Parse) is deprecated in favor of readGenericPackageDescription.

  • The function in PPSuffixHandler now takes an additional ComponentLocalBuildInfo specifying the build information of the component being preprocessed.

Deprecated functions

  • readPackageDescription (from Distribution.PackageDescription.Parse) is deprecated in favour of readGenericPackageDescription.

  • getComponentLocalBuildInfo, withComponentsInBuildOrder and componentsInBuildOrder are deprecated in favour of a new interface in "Distribution.Types.LocalBuildInfo".

  • finalizePackageDescription is deprecated: its replacement finalizePD now takes an extra argument ComponentRequestedSpec which specifies what components are to be enabled: use this instead of modifying the Component in a GenericPackageDescription. (As it's not possible now, finalizePackageDescription will assume tests/benchmarks are disabled.) If you only need to test if a component is buildable (i.e., it is marked buildable in the Cabal file) use the new function componentBuildable.

Clone this wiki locally