[Haskell-cafe] [ANN] haddock-2.15-0, haddock-api-2.15-0, haddock-library-1.1.1

[Mateusz Kowalczyk]

On 09/07/2014 09:10 AM, Joachim Breitner wrote:
> Hi,
> 
> 
> Am Sonntag, den 31.08.2014, 14:50 +0100 schrieb Mateusz Kowalczyk:
>> I'd like to announce the release of Haddock 2.15.0.
> 
> Cool.
> 
> How compatible are the .haddock files?

If you're coming from 2.14.3 then there is no problem. I think the last
change was at 2.14.0 so if you're on then you should be good to update.
If you're on 2.13.x or earlier then you'll have to regenerate all the
docs but IIRC the GHC versions that 2.13 and 2.14/15 are compatible with
are different anyway so you can't have both co-existing.

You can check what your current cversion is at through

haddock --compatible-interface-versions

although that flag has been a fairly recent addition (2.14.0). For
2.14.0-2.15.0 it is version ‘25’.

> In particular, and not only related to this upgrade: Under what
> condition can Debian upgrade haddock (resp. haddock-api resp.
> haddock-library) so that the .haddock files generated by the compiler
> build, using the haddock version that was shipped with GHC, can still be
> used?

tl;dr: as long as the interface doesn't change but when that actually
happens, depends. Personally I try to time this with a GHC release so
that people don't tend to notice as you normally don't mix the files
generated by different versions.

cheat sheet:
GHC 7.6.3 -> 7.8.3, no good, interface changed
2.14.0 ->* 2.15.0, all good, same interface
2.15.0 ->* future, no idea!

At the moment I think we don't have any changes in plans. If GHC 7.10
doesn't result in some big changes or we don't have new, breaking
features then it well may be possible that Haddock 2.16 or whatever it
will be at next GHC will be compatible with 7.8.2/7.8.3/7.10.x through
some CPP on our end to account for API changes. If it adds new
structures and stuff we need to store information about (PatternSynonyms
are an example of a thing that we'd need to store info about but that
wasn't around for 7.6.3) then we have to bump it.

It may well be that we could improve the way we store the interfaces,
such as store GHC version too and read that off so we know what we're
working with. This could make it a bit more future-proof but it'd be
difficult to maintain. Ironically, such a change would itself result in
an interface version bump.

Long-winded answer:

First a brief overview.

‘haddock’ is now simply a Main module over ‘haddock-api’, I think the
updates to ‘haddock’ in the future will simply be bumping the
‘haddock-api’ version in its cabal file so that it's easy to keep track.

‘haddock-api’ is where the bulk of the work is, all the nasty ‘talk to
GHC’ stuff and serialisation. This depends on ‘haddock-library’ which
means that if ‘haddock-library’ has breaking changes then ‘haddock-api’
has to be updated too.

‘haddock-library’ is the bits that don't need GHC, currently only the
parser but hopefully more in the future.

Ideally you want to use the latest version of each together with each
other but you can freely update ‘haddock-library’ as long as it didn't
have breaking changes. Currently ‘haddock-api’ has 1.1.1.* constraint.
and it should work with all matching versions.

In summary, if ‘haddock’ updates, you want to update ‘haddock-api’ too.
If ‘haddock-library’ makes a minor release, you can (but don't have to)
update it on its own. If it makes a breaking release then ‘haddock-api’
will be updated too. We'll basically make sure that the latest
‘haddock-api’ compiles with its ‘haddock-library’ constraint.

Now to try and answer your question:

it's fairly easy to find out if you're compatible simply with
--compatible-interface-versions. We update either when:

1. there was new markup

2. there was a GHC change that results in different binary format

So far I have not seen 2. happen yet but if it does happen, it will be
at new GHC release, changing this CPP:

binaryInterfaceVersion :: Word16
#if __GLASGOW_HASKELL__ == 708
binaryInterfaceVersion = 25

binaryInterfaceVersionCompatibility :: [Word16]
binaryInterfaceVersionCompatibility = [binaryInterfaceVersion]
#else
#error Unsupported GHC version
#endif

The 1. point doesn't happen often but it does happen, such as when I
added the new syntax for headers or bold; another example was when I
wanted to store language extensions used in the module. This was
coordinated with 7.8.x release so that most people wouldn't have noticed
there was interface change.

> Greetings,
> Joacihm
> 

-- 
Mateusz K.