项目作者: blitzcode

项目描述 :
Compare the public API of different versions of a Hackage library
高级语言: Haskell
项目地址: git://github.com/blitzcode/hackage-diff.git
创建时间: 2014-07-19T19:07:03Z
项目社区:https://github.com/blitzcode/hackage-diff

开源协议:MIT License

下载


hackage-diff

Compare the public API of different versions of a Hackage library. Detect breaking changes before you update or upload a new version.

Also available on Hackage.

Sample output for hackage-diff cereal 0.2 0.3.5.2:

  1. Downloading Hoogle DBs...
  2. Parsing Hoogle DBs...
  3. Comparing Hoogle DBs...
  4. --- Diff for | 0.2 0.3.5.2 | ---
  5. + Data.Serialize.IEEE754
  6. + getFloat32be :: Get Float
  7. + getFloat32le :: Get Float
  8. + getFloat64be :: Get Double
  9. + getFloat64le :: Get Double
  10. + putFloat32be :: Float -> Put
  11. + putFloat32le :: Float -> Put
  12. + putFloat64be :: Double -> Put
  13. + putFloat64le :: Double -> Put
  14. × Data.Serialize
  15. + instance Serialize a => GSerialize (K1 i a)
  16. + instance GSerialize a => GSerialize (M1 i c a)
  17. + instance (GSerialize a, GSerialize b) => GSerialize (a :*: b)
  18. + instance GSerialize U1
  19. + instance GSerialize a => GetSum (C1 c a)
  20. + instance (GetSum a, GetSum b, GSerialize a, GSerialize b) => GetSum (a :+: b)
  21. + instance GSerialize a => PutSum (C1 c a)
  22. + instance (PutSum a, PutSum b, GSerialize a, GSerialize b) => PutSum (a :+: b)
  23. + instance SumSize (C1 c a)
  24. + instance (SumSize a, SumSize b) => SumSize (a :+: b)
  25. + decodeLazy :: Serialize a => ByteString -> Either String a
  26. + encodeLazy :: Serialize a => a -> ByteString
  27. - data Get a
  28. - type Put = PutM ()
  29. - type Putter a = a -> Put
  30. - getWord8 :: Get Word8
  31. - putWord8 :: Putter Word8
  32. × Data.Serialize.Get
  33. + Done :: r -> ByteString -> Result r
  34. + instance Eq More
  35. + Fail :: String -> Result r
  36. + instance Functor Result
  37. + Partial :: (ByteString -> Result r) -> Result r
  38. + data Result r
  39. + instance Show r => Show (Result r)
  40. + ensure :: Int -> Get ByteString
  41. + runGetLazy :: Get a -> ByteString -> Either String a
  42. + runGetLazyState :: Get a -> ByteString -> Either String (a, ByteString)
  43. + runGetPartial :: Get a -> ByteString -> Result a
  44. × New: isolate :: Int -> Get a -> Get a
  45. Old: isolate :: String -> Int -> Get a -> Get a
  46. × Data.Serialize.Put
  47. + runPutLazy :: Put -> ByteString
  48. + runPutMLazy :: PutM a -> (a, ByteString)
  49. · Data.Serialize.Builder
  50. [+ Added] [- Removed] Modified] Unmodified]
  51. 6 potential breaking changes found

Terminal output can be colorized.

Usage

  1. hackage-diff | Compare the public API of different versions of a Hackage library
  2. github.com/blitzcode/hackage-diff | www.blitzcode.net | (C) 2014 Tim C. Schroeder
  3. Usage: hackage-diff [options] <package-name> <old-version|path> <new-version|path>
  4. --mode=[downloaddb|builddb|parsehs] what to download / read, how to compare
  5. downloaddb - download Hoogle DBs and diff (Default)
  6. builddb - download packages, build Hoogle DBs and diff
  7. parsehs - download packages, directly diff .hs exports
  8. -c --disable-color disable color output
  9. -s --silent disable progress output
  10. Examples:
  11. hackage-diff mtl 2.1 2.2.1
  12. hackage-diff --mode=builddb JuicyPixels 3.1.4.1 3.1.5.2
  13. hackage-diff conduit 1.1.5 ~/tmp/conduit-1.1.6/dist/doc/html/conduit/conduit.txt
  14. hackage-diff --mode=parsehs QuickCheck 2.6 2.7.6
  15. hackage-diff --mode=parsehs -s Cabal ~/tmp/Cabal-1.18.0/ 1.20.0.0

As the examples hopefully illustrate, you can choose to specify a local package / Hoogle database file instead of a version to be downloaded from Hackage.

Modes

hackage-diff can operate in three different modes which determine how it obtains and parses the information about the packages to be compared.

downloaddb

Download the Hoogle databases for both packages from Hackage, then parse and diff them. This is the default and recommended mode of operation. Sometimes Hackage does not have a Hoogle database for a particular version available. In this case, running with builddb might be more successful.

Alternatively, you can also specify a path to any local Hoogle database file for one or both versions. The default way to build one is cabal haddock --hoogle, outputting to dist/doc/html/mypackage/mypackage.txt. This can be used, among other things, to check a package you’re working on for breaking API changes relative to what’s on Hackage.

builddb

Download the package sources from Hackage, setup sandboxes, install dependencies, configure and use Haddock to build the Hoogle databases, parse and diff them.

This is often very time consuming due to the dependency installation required for the Haddock build. Sometimes Haddock builds will fail, especially for older packages. As with downloaddb, a local Hoogle database file can be specified instead of a version.

parsehs

Download the package sources from Hackage, parse .cabal file for exported modules, pre-process them with cpphs, parse them with haskel-src-exts and diff their export lists.

This mode has many downsides. Packages making heavy use of the CPP will often fail to be parsed as the pre-processing done here is not identical to what a Cabal build would do. haskel-src-exts sometimes fails to parse code that GHC would accept. We only look at the export lists, so modules without an explicit one will fail to be parsed correctly. There’s no inspection of the types of exports, only names will be compared.

Instead of a version to download, a path to a local package can be specified instead.

TODO

This tools has various shortcomings and limitations and has only received a small amount of testing. Please let me know if you find an issue. Also see the various TODO comments scattered throughout the code.

Legal

This program is published under the MIT License.

Author

Developed by Tim C. Schroeder, visit my website to learn more.