This is a friendly reminder to fix your Hackage documentation.
I’ve been feeling that over the last couple of months, I had to click on an older version of the package far more than before. Considering the Hackage 2 move around August, that was the first suspect. A quick chat in #hackage and it seems I was not the only one with that feeling, although no one could tell me what exactly was wrong.
Before I could went off on the mailing lists and asked for answers, I needed some numbers. People like numbers. If you’re not interested in this post, I ask that you at least read this thread on cabal-devel. Make sure you read the replies as I show how to do some things you might find useful.
Last night a scraped documentation information for the most recent version of all packages on Hackage. I do not have any more access to Hackage than most mere mortals do so this was the only way. Hackage API does exist but is very badly documented and it doesn’t seem to do JSON ever though it claims to do so and the relevant GitHub task is on ex-TODO. I used HXT to parse the output pages. You can see the hacky code as a Gist or as a file.
So considering this is a reminder, I better provide some information. You can find a list of package uploaded in 2013 and 2014 for which the documentation was deemed broken by clicking this. There are multiple reasons why a package could fail. To reiterate from the e-mail I sent to the mailing lists, here are failures we can’t do that much about:
- Dependencies fail to build so your package does
- Your package fails to build directly
- Your package requires non-cabal libraries which aren’t installed
- Your package requires different version of install libraries
There are however failures you can do something about straight away: Haddock failures. If your package was listed here and had ‘InstallOk’ next to it, your Haddock comments are probably wrong. This means you should view the build log and see what’s wrong.Viewing the Hackage build log
Here’s a very poorly but useful feature of Hackage: you can usually view your build log. If on my list, you have a MissingDocs reason that’s not ‘Nothing’, you can view this log. If it’s Nothing, sorry but you’re out of luck. See this comment on what is happening. I will show you how to upload documentation manually later for these cases.
- Identify your package version. My list shows this but you should also be able to just go on Hackage and see what’s broken. As an example, I’ll be using my tiny yi-monokai-0.1.1.1 package for which the build has failed.
- Read the build log. You can get the build status for Hackage packages like so: http://hackage.haskell.org/package/yi-monokai-0.1.1.1/reports/. Considering your package got InstallOk, this will exist. You can go to the first build status log like so: http://hackage.haskell.org/package/yi-monokai-0.1.1.1/reports/1 and you can get to the actual build log like this: http://hackage.haskell.org/package/yi-monokai-0.1.1.1/reports/1/log. The pattern should be easy to spot.
Somewhere at the bottom of the build log there should be a reason for failure. If it’s a Haddock error, fix it. I made your job easier and made a list of packages which seem to simply have malformed Haddock comments. I had manually fixed and formed pull request for the bottom third of these. It’s usually very easy to fix! See Haddock manual for help on syntax. You can also ping me on IRC (Fuuzetsu) and I’ll be happy to point out what might be wrong.
Another kind of failure one might get this way is HsColour failure: Hackage can run Haddock with --hyperlink-source and I saw an error yesterday caused by bad file encoding and HsColour failing. This is unusual (your files should be UTF-8 to begin with).
If all it is a Haddock parse error, simply fix it and upload a new version of the package. Anyone browsing will be grateful!
If it’s something else, read on.Uploading documentation manually
If your failure wasn’t a simple Haddock markup problem, it might not be plausible to have Hackage build your documentation. An easy example is missing C libraries. While ideally Hackage should have means of providing these, it currently doesn’t.
If you don’t have a build log for your package (‘Nothing’ on my list), this is probably the only way to get documentation too.
Here I’ll outline how to create and upload documentation by hand for your package. The change should immediate once uploaded.
Before you do this, check your build log. If it’s just a Haddock failure, fix it and upload the package afresh. Don’t upload documentation which differs from the actual package version.
You first need to make your documentation. I’ll be using ‘yi-monokai-0.1.1.1’ package as an example.
Navigate to your project’s directory:
Build package with documentation:
cabal configure && cabal build && cabal haddock --hyperlink-source
Navigate to where your documentation was generated.
Rename your docs directory to a format Hackage expects it in. It is ‘packagename-version-docs’.
mv yi-monokai yi-monokai-0.1.1.1-docs
Create an archive of your directory. It has to be in a specific format and you’ll need the --format=ustar flag.
tar -c -v -z -Hustar -f yi-monokai-0.1.1.1-docs.tar.gz yi-monokai-0.1.1.1-docs
Upload the docs to Hackage. You need to make a POST to a specific URL. Triple check your package version: you don’t want to be uploading documentation for the wrong thing. The username and password are your Hackage credentials.
curl -X PUT -H 'Content-Type: application/x-tar' -H 'Content-Encoding: gzip' --data-binary '@yi-monokai-0.1.1.1-docs.tar.gz' 'http://USERNAME:PASSWORD@hackage.haskell.org/package/yi-monokai-0.1.1.1/docs'
Go on Hackage and see whether it worked. Your docs should come up straight away. If they haven’t, worry. Check your URL. Make sure you didn’t get any error messages from Hackage when uploading the package.
Here’s a quick Bash script to automate it a bit: as a Gist or as a file. Perhaps a library to interface with Hackage needs to be written. In fact, that’d be pretty useful. Put it somewhere in your PATH, go into your project’s directory and use it like this:
hackagedocs yi-monokai 0.1.1.1 username password
It’s is very naive, I am in fact writing it while I’m writing this blog post. Please adjust the commands inside as you see necessary.
Disclaimer: I don’t know Bash, I’m just making stuff up from snippets of scripts I have lying around.
I hope I encouraged you to make your Hackage documentation work again! Have some fan service for making it all the way to the end of the tedious post.
EDIT: See updates to this post here, it tells you how to fix package cross-linking and stuff. Also, please keep reading the mailing list thread for further developments. Nice people post their scripts to do this stuff and in general these issues are discussed.
Backpack: Retrofitting Haskell with Interfaces
Scott Kilpatrick, Derek Dreyer, Simon Peyton Jones, Simon Marlow
Module systems like that of Haskell permit only a weak form of modularity in which module implementations directly depend on other implementations and must be processed in dependency order. Module systems like that of ML, on the other hand, permit a stronger form of modularity in which explicit interfaces express assumptions about dependencies, and each module can be typechecked and reasoned about independently.
In this paper, we present Backpack, a new language for building separately-typecheckable packages on top of a weak module system like Haskell's. The design of Backpack is inspired by the MixML module calculus of Rossberg and Dreyer, but differs significantly in detail. Like MixML, Backpack supports explicit interfaces and recursive linking. Unlike MixML, Backpack supports a more flexible applicative semantics of instantiation. Moreover, its design is motivated less by foundational concerns and more by the practical concern of integration into Haskell, which has led us to advocate simplicity—in both the syntax and semantics of Backpack—over raw expressive power. The semantics of Backpack packages is defined by elaboration to sets of Haskell modules and binary interface files, thus showing how Backpack maintains interoperability with Haskell while extending it with separate typechecking. Lastly, although Backpack is geared toward integration into Haskell, its design and semantics are largely agnostic with respect to the details of the underlying core language.
The scotty-hastache library has been updating, following the introduction of the custom exception types in Scotty. Custom exception types (as opposed to plain-text exception mechanism that was previously employed in Scotty) is a more powerful way of handling exceptional situation; an example usage can be found here. Below are the appropriate release notes for scotty-hastache0.2
Keeping up with the Scotty 0.6 updating. The introduction of the custom exception types is reflected in the scotty-hastache package as well. The main types are now polymorphic over an exception typetype ScottyH e = ScottyT e HState type ActionH e = ActionT e HState
In addition, the specialized (to Text) types and runners are introducedtype ScottyH' = ScottyH Text type ActionH' = ActionH Text scottyH' :: Port -> ScottyH' () -> IO () scottyHOpts' :: Options -> ScottyH' () -> IO ()
Thanks to Kirill Zaborsky for pointing out the incompatibility with 0.6.
Tagged: haskell, scotty, web
I've written the back-end for a simple Bridge (card game) bidding helper in Haskell as my first non-trivial project.
The idea is to expand this into a more useful general Bridge playing system. Before I go further, I'd really appreciate any feedback on the code: idiomatic use of Haskell; libraries I could have used; code formatting; anything!submitted by derek-mcloughlin
[link] [27 comments]
Leap day every 4 years.
Omit leap day every 33*4=132 years.
Keep leap day every 100*33*4=13200 years.
This sequence of multipliers [4,33,100] were found by the greedy method. The entire cycle has the same average year length as the Gregorian calendar = 365 + 97/400 days, which uses multipliers [4,25,4]. We alternate between keeping and omitting leap days at each larger multiplier.
countDays accum (h:t) offset = countDays (accum*h+offset) t (negate offset);
countDays accum  _ = accum;
averageYear :: [Integer] -> Rational;
averageYear leapPattern = (countDays 365 leapPattern 1) % (product leapPattern)
What is going on such that averageYear [4,33,100] == averageYear [4,25,4]? Find a set of multipliers which minimizes the product, i.e., cycle length. I suspect this is related to Egyptian fractions or continued fractions. I suspect that the greedy method yields a sequence which monotonically increases.
Update: these are Pierce expansions, a variant of Engel expansions.
Applying the greedy algorithm to 365 + 71/293 days (as proposed by the Symmetry454 calendar) yields multipliers [4,32,58,97,146,293] for a cycle of 11251521835008 days in 30805635584 years. (This is far less efficient than the 293 year cycle.)
When applied to adding "leap weeks" to the Gregorian calendar, we find the sequence [5,8,10] as reported in calendar based on 7. If we apply leap weeks to the 365+71/293 year-length, we get the sequence [5,8,10,97,146,293].