News aggregator

Mateusz Kowalczyk: Fix your Hackage documentation

Planet Haskell - Sun, 01/05/2014 - 7:17pm
Posted on January 6, 2014 by Fūzetsu

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.

  1. 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- package for which the build has failed.
  2. Read the build log. You can get the build status for Hackage packages like so: Considering your package got InstallOk, this will exist. You can go to the first build status log like so: and you can get to the actual build log like this: 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-’ package as an example.

  1. Navigate to your project’s directory:

    cd ~/programming/yi-monokai

  2. Build package with documentation:

    cabal configure && cabal build && cabal haddock --hyperlink-source

  3. Navigate to where your documentation was generated.

    cd dist/doc

  4. Rename your docs directory to a format Hackage expects it in. It is ‘packagename-version-docs’.

    mv yi-monokai yi-monokai-

  5. 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- yi-monokai-

  6. 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-' ''

  7. 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 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.

Categories: Offsite Blogs

Cloud Haskell, spawn, link and spawnLink

haskell-cafe - Sun, 01/05/2014 - 5:59pm
Hi. Let's consider the following code: pid <- spawnLocal ... link pid Is it true, that a parent process will always be terminated when child process terminates, even if child process will be terminated between calls of spawnLocal and link? I wrote a test program and it seems to be so. But I wanted to be sure, that this is not some coincidence, but a real Cloud Haskell semantics. Is the same true for monitors?
Categories: Offsite Discussion

Turning off warning in ghc-mod (in vim)

haskell-cafe - Sun, 01/05/2014 - 4:36pm
On the command line I can do the following: % ghc-mod check -g -isrc -g dist/build/autogen src/Main.hs | grep Top-level Binary file (standard input) matches % ghc-mod check -g -isrc -g dist/build/autogen -g -fno-warn-missing-signatures src/Main.hs | grep Top-level % That is, there is no output on the second call, just as expected. However, I can't work out out to turn off the warning in Vim. AFAIU the following should work: g:ghcmod_ghc_options = ['-isrc', '-idist/build/autogen', '-fno-warn-missing-signatures'] but it doesn't. I'm obviously missing something, but what? /M
Categories: Offsite Discussion

ProductProfunctor folds

Haskell on Reddit - Sun, 01/05/2014 - 2:06pm
Categories: Incoming News

relocation R_X86_64_PC32 against undefined symbol?

haskell-cafe - Sun, 01/05/2014 - 2:00pm
I get the following error when trying to build hsimports: [7 of 7] Compiling HsImport ( src/HsImport.hs, dist/build/HsImport.dyn_o ) /usr/bin/ld: dist/build/HsImport/Args.dyn_o: relocation R_X86_64_PC32 against undefined symbol `hsimportzm0zi2zi6zi3_Pathszuhsimport_version1_closure' can not be used when making a shared object; recompile with -fPIC /usr/bin/ld: final link failed: Bad value collect2: error: ld returned 1 exit status What could be causing this? /M
Categories: Offsite Discussion

Broken documentation on Hackage.

libraries list - Sun, 01/05/2014 - 12:15pm
Hi all, It seems that we are having a rather big issue with Hackage in recent months and I'm sure many of you have noticed: a lot of packages aren't getting their docs built. As far as I can tell, there can be multiple reasonable causes: * 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 While all of these are understandable, there also seem to be problems with some packages which are seemingly perfectly fine otherwise. This problem is not new and has been reported[1]. There is even a system in place with Hackage 2 that would grant package owners to manually upload documentation and a system where some people (trustees and package maintainers) have the ability to do things like deleting the broken docs to have the builder try again[3] but it seems that this isn't actually used[4]. Over night I hacked up a quick program to parse some Hackag
Categories: Offsite Discussion

Backpack: Retrofitting Haskell with a Module System, at last

Lambda the Ultimate - Sun, 01/05/2014 - 10:59am

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.

Categories: Offsite Discussion

Daniil Frumin: ANN: scotty-hastache 0.2

Planet Haskell - Sun, 01/05/2014 - 7:57am

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-hastache


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 type

type ScottyH e = ScottyT e HState type ActionH e = ActionT e HState

In addition, the specialized (to Text) types and runners are introduced

type 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.

As always, the scotty-hastache library is available on Hackage and on GitHub

Tagged: haskell, scotty, web
Categories: Offsite Blogs

My first non-trivial Haskell project - any help appreciated.

Haskell on Reddit - Sun, 01/05/2014 - 6:56am

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]
Categories: Incoming News

gist:8255552 - Sun, 01/05/2014 - 4:35am
Categories: Offsite Blogs

Ken T Takusagawa: [qupqknlc] Greedy leap years

Planet Haskell - Sun, 01/05/2014 - 4:12am

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].

Some disorganized Haskell code for these calculations.

Categories: Offsite Blogs - Sun, 01/05/2014 - 1:35am
Categories: Offsite Blogs - Sun, 01/05/2014 - 1:35am
Categories: Offsite Blogs

Emacs and our API | FP Complete - Sun, 01/05/2014 - 12:17am
Categories: Offsite Blogs

365 Tidal Patterns - Sun, 01/05/2014 - 12:07am
Categories: Offsite Blogs

Who remembers HP 2013.4.0.0...?

libraries list - Sat, 01/04/2014 - 11:35pm
I do - I'm just a lame-o this cycle! Please review the status below - I'll have the 'prerelease' branch in github updated this weekend, and packages out (src tarball and Mac installers) out this coming week. - Mark *Resolved Issues* - fgl - haven't heard from Ivan, so we'll stay with the status quo. - aeson / dlist - log round'a'bout discussion resulted in decision to omit aeson this cycle. - alex / happy - I haven't heard from the maintainers on the major version bump, but they are both active here and so I'm assuming it is a go. *Current Proposed Versions* *GHC 7.6.3* -- same as last time (erroneously listed as a version bump last time) *Packages with no changes:* fgl, haskell-src, html, HUnit, mtl, parsec, QuickCheck, random, regex-base, regex-compat, regex-posix, split, stm, text, transformers, xhtml, zlib *Packages held back:* cgi: 3001.1.7.5 (3001.1.8.4* requires MonadCatchIO-mtl)* *Packages with minor version bumps:* HTTP:
Categories: Offsite Discussion