From dave.laing.80 at gmail.com Fri Jan 3 12:50:44 2014 From: dave.laing.80 at gmail.com (David Laing) Date: Fri, 3 Jan 2014 22:50:44 +1000 Subject: Cabal hack night suggestions Message-ID: Hi all, There are a few people in my local FP meetup group looking into doing some semi-regular Haskell hack nights, and we're hoping to target various tools and libraries in the Haskell ecosystem so that we can give back a little while having fun and honing our skills. Cabal is pretty high on our list of things to hack on, and we're hoping to start mid next week. I'm sure we'll be able to click through github issues and submit pull requests on our own, but I thought I'd ask if anyone has any thoughts on areas that would be good to look at that might sit in a sweet spot of being both beneficial to Cabal and accessible to newcomers to the code. Does anyone have any thoughts? Cheers, Dave -------------- next part -------------- An HTML attachment was scrubbed... URL: From carter.schonwald at gmail.com Sun Jan 5 00:58:30 2014 From: carter.schonwald at gmail.com (Carter Schonwald) Date: Sat, 4 Jan 2014 19:58:30 -0500 Subject: hackage helpers!! Message-ID: hey all, isn't there supposed to be an ACLs level for hackage helpers? (ie folks who can force docbuilders to rebuild docs for packager, edit pkg info stuff, etc?) Am I correct in thinking no ones in that group yet? (i know duncan asked for volunteers, but I don't think anyone's been put in that group yet!) cheers! -Carter -------------- next part -------------- An HTML attachment was scrubbed... URL: From fuuzetsu at fuuzetsu.co.uk Sun Jan 5 10:15:31 2014 From: fuuzetsu at fuuzetsu.co.uk (Mateusz Kowalczyk) Date: Sun, 05 Jan 2014 10:15:31 +0000 Subject: Broken documentation on Hackage. Message-ID: <52C930C3.4080800@fuuzetsu.co.uk> 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 Hackage parts to see just how much stuff was broken. I have only considered the most recent package versions. Out of the 7761 packages, 811 came up with missing documentations. While it is a big number (~9.56%), it includes every package on Hackage. Next thing that follows is to restrict the search a bit. Only considering packages from 2013 and the still very young 2014, 210 are missing documentation. 140 of those were uploaded since August 2013 (around the Hackage 2 move). Remember that this is only for most recent versions on Hackage. Assuming that we didn't have a large spike in package uploads in second half of 2013 (I don't know, are there any charts or something?), that's unreasonably more than in the first half of 2013. It should be fairly clear that something is broken and I'd love to know what. I snooped around in #hackage today for a bit and there doesn't seem to be much sense of the urgency. Granted, people are busy but isn't this a pretty important issue? It's not like it's recent either. What can we do? Why isn't it fixed? Are there any suspects? Why isn't the trustee system being used to mitigate this problem a bit while it's being fixed? Is there any way to improve the amount of things that can be built by trying to work out any of the points at the top of this e-mail? Honestly, scrolling through the build logs of packages, all failures seem reasonable (Haddock parse failure, no dependencies installed?) and yet somehow I find myself having to click on older version of packages to get docs very often recently. What changed? Is there even anything to fix? Maybe I'm just getting unlucky with the packages I click on recently. I have uploaded the list of packages with missing documentation that have been uploaded on Hackage in 2013 and 2014 to [5]. The format is: (packageUrl, MissingDocs (Maybe reason) packageVersion dateUploaded). If your package is on there, you might want to consider uploading the docs by hand for now! Packages with ?Nothing? for a reason have no build log. See [6] for a reason for those. See [7] for how to view build logs yourself. PS: I'm unsure if these are the right lists to e-mail. I've been told that Cabal folk maintain Hackage issues and considering so many broken docs, libraries might also be interested in it. Feel free to point me elsewhere. PPS: There also seems to be a lot of 404 errors while trying to click on some docs on some older packages that probably existed in the past. Perhaps they were lost in the Hackage move or are a different issue all together. [1]: https://github.com/haskell/hackage-server/issues/145 [2]: https://github.com/haskell/hackage-server/issues/145#issuecomment-29468613 [3]: https://github.com/haskell/hackage-server/issues/145#issuecomment-29422332 [4]: http://hackage.haskell.org/packages/trustees/ [5]: http://fuuzetsu.co.uk/misc/sorted.txt [6]: https://github.com/haskell/hackage-server/issues/145#issuecomment-30129142 [7]: https://github.com/haskell/hackage-server/issues/145#issuecomment-29472445 -- Mateusz K. From daniel.trstenjak at gmail.com Sun Jan 5 10:37:23 2014 From: daniel.trstenjak at gmail.com (Daniel Trstenjak) Date: Sun, 5 Jan 2014 11:37:23 +0100 Subject: Warning about missing modules in 'other-modules' Message-ID: <20140105103723.GA13336@machine> Hi, I now at least twice ran into the issue, that I forgot to add a module to the 'other-modules' section of the cabal file and uploaded a non buildable package to hackage. It would be nice if 'cabal sdist' or 'cabal upload' would warn the user about missing modules. I just tried 'cabal upload -c', but I'm getting: $ cabal upload -c dist/hsimport-0.2.6.2.tar.gz Checking dist/hsimport-0.2.6.2.tar.gz... Error: dist/hsimport-0.2.6.2.tar.gz: 404 Not Found Error: Page not found Sorry, it's just not here. $ cabal --version cabal-install version 1.18.0.2 using version 1.18.1 of the Cabal library It seems that currently the best way to guarantee a buildable package is to build the tarbar with 'cabal sdist' and then install this tarball with 'cabal install', right? Greetings, Daniel From hesselink at gmail.com Sun Jan 5 14:09:03 2014 From: hesselink at gmail.com (Erik Hesselink) Date: Sun, 5 Jan 2014 15:09:03 +0100 Subject: Warning about missing modules in 'other-modules' In-Reply-To: <20140105103723.GA13336@machine> References: <20140105103723.GA13336@machine> Message-ID: On Sun, Jan 5, 2014 at 11:37 AM, Daniel Trstenjak wrote: > It would be nice if 'cabal sdist' or 'cabal upload' would warn the user > about missing modules. This was built to run during 'cabal build' [0] but deemed too slow. See the issue for a possible future direction. > It seems that currently the best way to guarantee a buildable package is > to build the tarbar with 'cabal sdist' and then install this tarball > with 'cabal install', right? I think so, yes. Regards, Erik [0] https://github.com/haskell/cabal/pull/1455 From selinger at mathstat.dal.ca Sun Jan 5 18:15:01 2014 From: selinger at mathstat.dal.ca (Peter Selinger) Date: Sun, 5 Jan 2014 14:15:01 -0400 (AST) Subject: Broken documentation on Hackage. In-Reply-To: <52C930C3.4080800@fuuzetsu.co.uk> Message-ID: <20140105181501.D1D528C017C@chase.mathstat.dal.ca> I agree. Two of my packages are in your list: easyrender and newsynth (both have "Nothing" for a reason in your list). The problem for me is that, although you seem to have access to build logs, I don't. I have not found the way to access the hackage build logs for my packages or their documentation. Could you let me know where I can find them? For both packages, the documentation builds just fine on my local machine. It also builds fine in a virtual machine, under Windows and Ubuntu. Since I don't have access to Hackage's build logs, I cannot really figure out why the documentation is not building there. This is what has prevented me from fixing it. I even created "candidates" for the packages, before uploading the packages to the main index. Again, the documentation did not build, and again, I could not find any logs to tell me what went wrong. So the whole "candidate" mechanism has so far been useless to me. You mentioned that there is a way to upload the documentation manually. I'd love to do that. But how? I don't see any buttons or links on the package maintainer's pages that would allow me to do that. Any help appreciated, -- Peter Mateusz Kowalczyk wrote: > > 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 Hackage parts to > see just how much stuff was broken. I have only considered the most > recent package versions. Out of the 7761 packages, 811 came up with > missing documentations. While it is a big number (~9.56%), it includes > every package on Hackage. Next thing that follows is to restrict the > search a bit. Only considering packages from 2013 and the still very > young 2014, 210 are missing documentation. 140 of those were uploaded > since August 2013 (around the Hackage 2 move). Remember that this is > only for most recent versions on Hackage. Assuming that we didn't have a > large spike in package uploads in second half of 2013 (I don't know, are > there any charts or something?), that's unreasonably more than in the > first half of 2013. > > It should be fairly clear that something is broken and I'd love to know > what. I snooped around in #hackage today for a bit and there doesn't > seem to be much sense of the urgency. Granted, people are busy but isn't > this a pretty important issue? It's not like it's recent either. > > What can we do? Why isn't it fixed? Are there any suspects? Why isn't > the trustee system being used to mitigate this problem a bit while it's > being fixed? Is there any way to improve the amount of things that can > be built by trying to work out any of the points at the top of this > e-mail? Honestly, scrolling through the build logs of packages, all > failures seem reasonable (Haddock parse failure, no dependencies > installed=85) and yet somehow I find myself having to click on older > version of packages to get docs very often recently. What changed? Is > there even anything to fix? Maybe I'm just getting unlucky with the > packages I click on recently. > > I have uploaded the list of packages with missing documentation that > have been uploaded on Hackage in 2013 and 2014 to [5]. The format is: > (packageUrl, MissingDocs (Maybe reason) packageVersion dateUploaded). If > your package is on there, you might want to consider uploading the docs > by hand for now! Packages with =91Nothing=92 for a reason have no build log. > See [6] for a reason for those. See [7] for how to view build logs yourself. > > PS: I'm unsure if these are the right lists to e-mail. I've been told > that Cabal folk maintain Hackage issues and considering so many broken > docs, libraries might also be interested in it. Feel free to point me > elsewhere. > PPS: There also seems to be a lot of 404 errors while trying to click on > some docs on some older packages that probably existed in the past. > Perhaps they were lost in the Hackage move or are a different issue all > together. > > [1]: https://github.com/haskell/hackage-server/issues/145 > [2]: > https://github.com/haskell/hackage-server/issues/145#issuecomment-29468613 > [3]: > https://github.com/haskell/hackage-server/issues/145#issuecomment-29422332 > [4]: http://hackage.haskell.org/packages/trustees/ > [5]: http://fuuzetsu.co.uk/misc/sorted.txt > [6]: > https://github.com/haskell/hackage-server/issues/145#issuecomment-30129142 > [7]: > https://github.com/haskell/hackage-server/issues/145#issuecomment-29472445 > -- = > > Mateusz K. > _______________________________________________ > cabal-devel mailing list > cabal-devel at haskell.org > http://www.haskell.org/mailman/listinfo/cabal-devel > From fuuzetsu at fuuzetsu.co.uk Sun Jan 5 22:38:14 2014 From: fuuzetsu at fuuzetsu.co.uk (Mateusz Kowalczyk) Date: Sun, 05 Jan 2014 22:38:14 +0000 Subject: Broken documentation on Hackage. In-Reply-To: References: <52C930C3.4080800@fuuzetsu.co.uk> Message-ID: <52C9DED6.2080405@fuuzetsu.co.uk> On 05/01/14 14:14, Sven Panne wrote: > My ALUT package is among the ones without documentation, and I have a > theory what's wrong (probably a missing installed C library/package > libalut-dev, see > https://github.com/haskell-openal/ALUT/blob/master/.travis.yml). Two > questions: > > * As a package maintainer, how can I find out why the documentation > is not built/published on Hackage? Logs, etc.? I mention a link to a GitHub post in my opening post which outlines how to access the log. In case of ALUT, the build log is at [1] http://hackage.haskell.org/package/ALUT-2.3.0.1/reports/1/log and indeed a C library is missing. > * Who should be contacted to polish the server a bit (i.e. install > libalut-dev)? No idea, but I'd love to find out myself! I'm just a disgruntled Hackage user myself. > Currently things are very opaque from the outside, both from a > technical and from an organizational point of view, and manually > uploading documentation which is effectively guaranteed to be > wrong/outdated/etc. sooner or later is not a solution IMHO. You would be uploading documentation for a specific package version. So for example, if you upload something for ALUT 2.3.0.1 and later upload upload ALUT 2.4, either the docs will be built fine (which would be ideal) or you will have to upload them yourself again for that version. I agree that this is subpar but I think it's better than nothing. There should really be a ?upload documentation? button on the site or maybe even a Cabal flag or maybe even ability to bundle documentation in the package tarball when uploading it, to act as a fallback if package fails to build. I suppose this is something that has to be discussed. Ideally, it should just work. > > Cheers, > S. > [1]: http://hackage.haskell.org/package/ALUT-2.3.0.1/reports/1/log -- Mateusz K. From fuuzetsu at fuuzetsu.co.uk Sun Jan 5 23:18:33 2014 From: fuuzetsu at fuuzetsu.co.uk (Mateusz Kowalczyk) Date: Sun, 05 Jan 2014 23:18:33 +0000 Subject: Broken documentation on Hackage. In-Reply-To: <20140105181501.D1D528C017C@chase.mathstat.dal.ca> References: <20140105181501.D1D528C017C@chase.mathstat.dal.ca> Message-ID: <52C9E849.4080400@fuuzetsu.co.uk> On 05/01/14 18:15, Peter Selinger wrote: > I agree. Two of my packages are in your list: easyrender and newsynth > (both have "Nothing" for a reason in your list). If a package has Nothing for a reason, that means that no build log is available. From what I've read yesterday, it's a problem with their report system and I think it happens when cabal can't find dependency candidates for your package. I link to a comment on GitHub in my opening post which explains this. > The problem for me is that, although you seem to have access to build > logs, I don't. I have not found the way to access the hackage build > logs for my packages or their documentation. Could you let me know > where I can find them? I do not have any special access to Hackage, I didn't even log in. See my opening post for how to access the build log or see my reply to Sven for an example. I really think there should be a button on the site for this. If the build logs existed for newsynth, you could do the following: check general build status[1] then check the first report[2] then check the build log for the first report[3]. If the build status is empty, you won't have any reports. Check out [4][5][6] for an example on a package which failed to build and has logs. Effectively, the Nothing in my ?report? indicates no build status. > For both packages, the documentation builds just fine on my local > machine. It also builds fine in a virtual machine, under Windows and > Ubuntu. Since I don't have access to Hackage's build logs, I cannot > really figure out why the documentation is not building there. This is > what has prevented me from fixing it. I suspect Hackage fails to resolve your dependencies, at least that what seems to be causing no logs. See [7] for a comment and [8] for an existing GitHub issue (although one without any activity). > I even created "candidates" for the packages, before uploading the > packages to the main index. Again, the documentation did not build, > and again, I could not find any logs to tell me what went wrong. So > the whole "candidate" mechanism has so far been useless to me. > > You mentioned that there is a way to upload the documentation > manually. I'd love to do that. But how? I don't see any buttons or > links on the package maintainer's pages that would allow me to do > that. I post a link in my opening post to a comment about this. See [9]. I just tried to do it for one of my packages (yi-monokai-0.1.1.1) and here are the steps I took: 1. cd ~/programming/yi-monokai 2. cabal configure && cabal build && cabal haddock --hyperlink-source 3. cd dist/doc 4. mv yi-monokai yi-monokai-0.1.1.1-docs 5. tar -c -v -z -Hustar -f yi-monokai-0.1.1.1-docs.tar.gz yi-monokai-0.1.1.1-docs 6. 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 at hackage.haskell.org/package/yi-monokai-0.1.1.1/docs' With these steps, my little package now has documentation. There's some info on format at [10]. I might write a small blog post outlining these steps later as it was not easy to figure out. > Any help appreciated, -- Peter [1]: http://hackage.haskell.org/package/newsynth-0.1.0.0/reports/ [2]: http://hackage.haskell.org/package/newsynth-0.1.0.0/reports/1 [3]: http://hackage.haskell.org/package/newsynth-0.1.0.0/reports/1/log [4]: http://hackage.haskell.org/package/yi-monokai-0.1.1.1/reports/ [5]: http://hackage.haskell.org/package/yi-monokai-0.1.1.1/reports/1 [6]: http://hackage.haskell.org/package/yi-monokai-0.1.1.1/reports/1/log [7]: https://github.com/haskell/hackage-server/issues/145#issuecomment-30129142 [8]: https://github.com/haskell/hackage-server/issues/142 [9]: https://github.com/haskell/hackage-server/issues/145#issuecomment-29468613 [10]: https://github.com/haskell/hackage-server/issues/56 -- Mateusz K. From malcolm.wallace at me.com Mon Jan 6 10:27:21 2014 From: malcolm.wallace at me.com (Malcolm Wallace) Date: Mon, 06 Jan 2014 10:27:21 +0000 Subject: Broken documentation on Hackage. In-Reply-To: <52C930C3.4080800@fuuzetsu.co.uk> References: <52C930C3.4080800@fuuzetsu.co.uk> Message-ID: On 5 Jan 2014, at 10:15, Mateusz Kowalczyk wrote: > 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 I think the fundamental problem is that Haddock is now built on top of ghc. So if a package cannot be built by ghc (for whatever reason, e.g. missing C library dependency), then it cannot be documented either. This is a good deal less than useful. A documentation generator ought to do a reasonable job, even if the code it is looking at is technically not-compilable. At work, we have a stand-alone documentation generator for Haskell, which requires no compiler. Haddock also was once stand-alone. I think it might be time to wind the clock backwards and retrieve this desirable property. Regards, Malcolm From fuuzetsu at fuuzetsu.co.uk Mon Jan 6 12:02:35 2014 From: fuuzetsu at fuuzetsu.co.uk (Mateusz Kowalczyk) Date: Mon, 06 Jan 2014 12:02:35 +0000 Subject: Broken documentation on Hackage. In-Reply-To: <52CA8AC3.1020508@henning-thielemann.de> References: <52C930C3.4080800@fuuzetsu.co.uk> <52CA8AC3.1020508@henning-thielemann.de> Message-ID: <52CA9B5B.6080006@fuuzetsu.co.uk> Oops, seems I sent to libraries. Let's keep the thread on cabal-devel only as here's where the replies happened. On 06/01/14 10:27, Malcolm Wallace wrote: > > On 5 Jan 2014, at 10:15, Mateusz Kowalczyk wrote: > >> 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 > > I think the fundamental problem is that Haddock is now built on top of ghc. So if a package cannot be built by ghc (for whatever reason, e.g. missing C library dependency), then it cannot be documented either. This is a good deal less than useful. A documentation generator ought to do a reasonable job, even if the code it is looking at is technically not-compilable. It is because it uses GHC to type check the modules and generate the signatures. I agree that there should be some kind of fall back but it would be a great deal less useful of an output. > At work, we have a stand-alone documentation generator for Haskell, which requires no compiler. Haddock also was once stand-alone. I think it might be time to wind the clock backwards and retrieve this desirable property. Was Haddock ever stand alone? AFAIK it used to be part of GHC and then David Waern separated it into a separate package. I honestly can't think of how it would ever have been stand-alone (that is not relying on GHC to do part of the work). > > Regards, -- Mateusz K. From johan.tibell at gmail.com Mon Jan 6 12:53:43 2014 From: johan.tibell at gmail.com (Johan Tibell) Date: Mon, 6 Jan 2014 13:53:43 +0100 Subject: Cabal hack night suggestions In-Reply-To: References: Message-ID: Hi David, Great to here that you're going to hack on cabal. We need all the contributors we can get! The general roadmap for 1.20 is here: http://www.haskell.org/pipermail/cabal-devel/2013-September/009533.html The "Do the right thing automatically" section is probably the most newbie friendly. Other than that we really need to get the bug tracker under control. This means triaging bugs and fixing those that need fixing and closing the rest. I took a stab at this a while ago but if you want something to get your feet wet, I suggest grabbing something that looks interesting from the bug tracker. As for hacking on cabal, I suggest using sandboxes, like so: cd cabal/cabal-install # only once: cabal sandbox init cabal sandbox add-source ../Cabal cabal install -j --only-dep # to (re)build: cabal build -- Johan On Fri, Jan 3, 2014 at 1:50 PM, David Laing wrote: > Hi all, > > There are a few people in my local FP meetup group looking into doing some > semi-regular Haskell hack nights, and we're hoping to target various tools > and libraries in the Haskell ecosystem so that we can give back a little > while having fun and honing our skills. > > Cabal is pretty high on our list of things to hack on, and we're hoping to > start mid next week. > > I'm sure we'll be able to click through github issues and submit pull > requests on our own, but I thought I'd ask if anyone has any thoughts on > areas that would be good to look at that might sit in a sweet spot of being > both beneficial to Cabal and accessible to newcomers to the code. > > Does anyone have any thoughts? > > Cheers, > > Dave > > _______________________________________________ > cabal-devel mailing list > cabal-devel at haskell.org > http://www.haskell.org/mailman/listinfo/cabal-devel > > -------------- next part -------------- An HTML attachment was scrubbed... URL: From malcolm.wallace at me.com Mon Jan 6 13:46:22 2014 From: malcolm.wallace at me.com (Malcolm Wallace) Date: Mon, 06 Jan 2014 13:46:22 +0000 Subject: Broken documentation on Hackage. In-Reply-To: <52CAA246.3080806@henning-thielemann.de> References: <52C930C3.4080800@fuuzetsu.co.uk> <52CA9AA7.6020604@fuuzetsu.co.uk> <52CAA246.3080806@henning-thielemann.de> Message-ID: <731AB412-609C-4838-871E-9217B7754A4E@me.com> On 6 Jan 2014, at 12:32, Henning Thielemann wrote: > Am 06.01.2014 12:59, schrieb Mateusz Kowalczyk: >> On 06/01/14 10:27, Malcolm Wallace wrote: >>> >>> Haddock also was once stand-alone. I think it might be time to wind the clock backwards and retrieve this desirable property. >> >> Was Haddock ever stand alone? AFAIK it used to be part of GHC and then >> David Waern separated it into a separate package. > > The versions with leading zero by Simon Marlow used a custom parser. Yes, early versions of Haddock assumed that the developer would always write a type signature for any top-level value that is exported. No need to rely on a compiler to infer a type. Although inference is hugely useful, I think the discipline of actually writing down what the compiler infers for you is an absolutely essential software engineering practice. It is one good step towards future maintainability of the library. At my workplace, for instance, our git repo infrastructure is configured to reject any code that exports a value without an explicit type signature. Regards, Malcolm From allbery.b at gmail.com Mon Jan 6 14:33:19 2014 From: allbery.b at gmail.com (Brandon Allbery) Date: Mon, 6 Jan 2014 09:33:19 -0500 Subject: Broken documentation on Hackage. In-Reply-To: References: <52C930C3.4080800@fuuzetsu.co.uk> Message-ID: On Mon, Jan 6, 2014 at 5:27 AM, Malcolm Wallace wrote: > > I think the fundamental problem is that Haddock is now built on top of > ghc. So if a package cannot be built by ghc (for whatever reason, e.g. > missing C library dependency), then it cannot be documented either. This > is a good deal less than useful. A documentation generator ought to do a > reasonable job, even if the code it is looking at is technically > not-compilable. > > At work, we have a stand-alone documentation generator for Haskell, which > requires no compiler. Haddock also was once stand-alone. I think it might > be time to wind the clock backwards and retrieve this desirable property. > The problem with that was you didn't get documentation if you used any GHC extension added within the past year or so. You can't win.... -- brandon s allbery kf8nh sine nomine associates allbery.b at gmail.com ballbery at sinenomine.net unix, openafs, kerberos, infrastructure, xmonad http://sinenomine.net -------------- next part -------------- An HTML attachment was scrubbed... URL: From johan.tibell at gmail.com Mon Jan 6 15:38:59 2014 From: johan.tibell at gmail.com (Johan Tibell) Date: Mon, 6 Jan 2014 16:38:59 +0100 Subject: Broken documentation on Hackage. In-Reply-To: References: <52C930C3.4080800@fuuzetsu.co.uk> Message-ID: On Mon, Jan 6, 2014 at 3:33 PM, Brandon Allbery wrote: > On Mon, Jan 6, 2014 at 5:27 AM, Malcolm Wallace wrote: >> >> I think the fundamental problem is that Haddock is now built on top of >> ghc. So if a package cannot be built by ghc (for whatever reason, e.g. >> missing C library dependency), then it cannot be documented either. This >> is a good deal less than useful. A documentation generator ought to do a >> reasonable job, even if the code it is looking at is technically >> not-compilable. >> >> At work, we have a stand-alone documentation generator for Haskell, which >> requires no compiler. Haddock also was once stand-alone. I think it might >> be time to wind the clock backwards and retrieve this desirable property. >> > > The problem with that was you didn't get documentation if you used any GHC > extension added within the past year or so. You can't win.... > This problem keeps popping up in our various tooling efforts so I thought it'd be worth pointing out that the general problem has been discussed in a paper. Martin Odersky touched on the more general problem of trying to have two * complete (e.g. supporting all extensions in our case) and * identically behaving implementations of the same compiler (or part of a compiler in our case) in the Scalable Component Abstractions paper [1]. It is very difficult and requires a huge amount of work. The Scala solution is the cake pattern which lets the Scala compiler expose itself as two different APIs, used for two different purposes (in their case the compiler proper and a reflection API). Even if relying on the GHC API is a bit of a pain, it's better than relying on a subtly different implementation that supports some subset of the features. 1. http://lampwww.epfl.ch/~odersky/papers/ScalableComponent.pdf -------------- next part -------------- An HTML attachment was scrubbed... URL: From selinger at mathstat.dal.ca Mon Jan 6 20:00:55 2014 From: selinger at mathstat.dal.ca (Peter Selinger) Date: Mon, 6 Jan 2014 16:00:55 -0400 (AST) Subject: Broken documentation on Hackage. In-Reply-To: <52C9E849.4080400@fuuzetsu.co.uk> Message-ID: <20140106200056.06D1D8C017C@chase.mathstat.dal.ca> Thank you, this worked like a charm! (Modulo using dist/doc/html instead of dist/doc). Now all my packages have online documentation. One day I'd still like to find out why it didn't build automatically. But as long as documentation builder doesn't generate a log saying what problem it thought could not be solved, there is no way of knowing really. Thanks again, -- Peter Mateusz Kowalczyk wrote: > > On 05/01/14 18:15, Peter Selinger wrote: > > I agree. Two of my packages are in your list: easyrender and newsynth > > (both have "Nothing" for a reason in your list). > > If a package has Nothing for a reason, that means that no build log is > available. From what I've read yesterday, it's a problem with their > report system and I think it happens when cabal can't find > dependency candidates for your package. I link to a comment on GitHub > in my opening post which explains this. > > > The problem for me is that, although you seem to have access to build > > logs, I don't. I have not found the way to access the hackage build > > logs for my packages or their documentation. Could you let me know > > where I can find them? > > I do not have any special access to Hackage, I didn't even log in. See > my opening post for how to access the build log or see my reply to > Sven for an example. I really think there should be a button on the > site for this. If the build logs existed for newsynth, you could do > the following: check general build status[1] then check the first > report[2] then check the build log for the first report[3]. If the > build status is empty, you won't have any reports. > > Check out [4][5][6] for an example on a package which failed to build > and has logs. > > Effectively, the Nothing in my ?report? indicates no build status. > > > For both packages, the documentation builds just fine on my local > > machine. It also builds fine in a virtual machine, under Windows and > > Ubuntu. Since I don't have access to Hackage's build logs, I cannot > > really figure out why the documentation is not building there. This is > > what has prevented me from fixing it. > > I suspect Hackage fails to resolve your dependencies, at least that > what seems to be causing no logs. See [7] for a comment and [8] for an > existing GitHub issue (although one without any activity). > > > I even created "candidates" for the packages, before uploading the > > packages to the main index. Again, the documentation did not build, > > and again, I could not find any logs to tell me what went wrong. So > > the whole "candidate" mechanism has so far been useless to me. > > > > You mentioned that there is a way to upload the documentation > > manually. I'd love to do that. But how? I don't see any buttons or > > links on the package maintainer's pages that would allow me to do > > that. > > I post a link in my opening post to a comment about this. See [9]. > I just tried to do it for one of my packages (yi-monokai-0.1.1.1) and > here are the steps I took: > > 1. cd ~/programming/yi-monokai > 2. cabal configure && cabal build && cabal haddock --hyperlink-source > 3. cd dist/doc > 4. mv yi-monokai yi-monokai-0.1.1.1-docs > 5. tar -c -v -z -Hustar -f yi-monokai-0.1.1.1-docs.tar.gz > yi-monokai-0.1.1.1-docs > 6. 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 at hackage.haskell.org/package/yi-monokai-0.1.1.1/docs' > > With these steps, my little package now has documentation. There's > some info on format at [10]. I might write a small blog post outlining > these steps later as it was not easy to figure out. > > > Any help appreciated, -- Peter > > [1]: http://hackage.haskell.org/package/newsynth-0.1.0.0/reports/ > [2]: http://hackage.haskell.org/package/newsynth-0.1.0.0/reports/1 > [3]: http://hackage.haskell.org/package/newsynth-0.1.0.0/reports/1/log > [4]: http://hackage.haskell.org/package/yi-monokai-0.1.1.1/reports/ > [5]: http://hackage.haskell.org/package/yi-monokai-0.1.1.1/reports/1 > [6]: > http://hackage.haskell.org/package/yi-monokai-0.1.1.1/reports/1/log > [7]: > https://github.com/haskell/hackage-server/issues/145#issuecomment-30129142 > [8]: https://github.com/haskell/hackage-server/issues/142 > [9]: > https://github.com/haskell/hackage-server/issues/145#issuecomment-29468613 > [10]: https://github.com/haskell/hackage-server/issues/56 > -- > Mateusz K. > From carter.schonwald at gmail.com Mon Jan 6 20:25:29 2014 From: carter.schonwald at gmail.com (Carter Schonwald) Date: Mon, 6 Jan 2014 15:25:29 -0500 Subject: Broken documentation on Hackage. In-Reply-To: <20140106200056.06D1D8C017C@chase.mathstat.dal.ca> References: <52C9E849.4080400@fuuzetsu.co.uk> <20140106200056.06D1D8C017C@chase.mathstat.dal.ca> Message-ID: i'm sure patches are welcome to improve hackage infrastructure in these ways! :) On Mon, Jan 6, 2014 at 3:00 PM, Peter Selinger wrote: > Thank you, this worked like a charm! (Modulo using dist/doc/html > instead of dist/doc). Now all my packages have online documentation. > > One day I'd still like to find out why it didn't build automatically. > But as long as documentation builder doesn't generate a log saying > what problem it thought could not be solved, there is no way of > knowing really. > > Thanks again, -- Peter > > Mateusz Kowalczyk wrote: > > > > On 05/01/14 18:15, Peter Selinger wrote: > > > I agree. Two of my packages are in your list: easyrender and newsynth > > > (both have "Nothing" for a reason in your list). > > > > If a package has Nothing for a reason, that means that no build log is > > available. From what I've read yesterday, it's a problem with their > > report system and I think it happens when cabal can't find > > dependency candidates for your package. I link to a comment on GitHub > > in my opening post which explains this. > > > > > The problem for me is that, although you seem to have access to build > > > logs, I don't. I have not found the way to access the hackage build > > > logs for my packages or their documentation. Could you let me know > > > where I can find them? > > > > I do not have any special access to Hackage, I didn't even log in. See > > my opening post for how to access the build log or see my reply to > > Sven for an example. I really think there should be a button on the > > site for this. If the build logs existed for newsynth, you could do > > the following: check general build status[1] then check the first > > report[2] then check the build log for the first report[3]. If the > > build status is empty, you won't have any reports. > > > > Check out [4][5][6] for an example on a package which failed to build > > and has logs. > > > > Effectively, the Nothing in my ?report? indicates no build status. > > > > > For both packages, the documentation builds just fine on my local > > > machine. It also builds fine in a virtual machine, under Windows and > > > Ubuntu. Since I don't have access to Hackage's build logs, I cannot > > > really figure out why the documentation is not building there. This is > > > what has prevented me from fixing it. > > > > I suspect Hackage fails to resolve your dependencies, at least that > > what seems to be causing no logs. See [7] for a comment and [8] for an > > existing GitHub issue (although one without any activity). > > > > > I even created "candidates" for the packages, before uploading the > > > packages to the main index. Again, the documentation did not build, > > > and again, I could not find any logs to tell me what went wrong. So > > > the whole "candidate" mechanism has so far been useless to me. > > > > > > You mentioned that there is a way to upload the documentation > > > manually. I'd love to do that. But how? I don't see any buttons or > > > links on the package maintainer's pages that would allow me to do > > > that. > > > > I post a link in my opening post to a comment about this. See [9]. > > I just tried to do it for one of my packages (yi-monokai-0.1.1.1) and > > here are the steps I took: > > > > 1. cd ~/programming/yi-monokai > > 2. cabal configure && cabal build && cabal haddock --hyperlink-source > > 3. cd dist/doc > > 4. mv yi-monokai yi-monokai-0.1.1.1-docs > > 5. tar -c -v -z -Hustar -f yi-monokai-0.1.1.1-docs.tar.gz > > yi-monokai-0.1.1.1-docs > > 6. 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 at hackage.haskell.org/package/yi-monokai-0.1.1.1/docs > ' > > > > With these steps, my little package now has documentation. There's > > some info on format at [10]. I might write a small blog post outlining > > these steps later as it was not easy to figure out. > > > > > Any help appreciated, -- Peter > > > > [1]: http://hackage.haskell.org/package/newsynth-0.1.0.0/reports/ > > [2]: http://hackage.haskell.org/package/newsynth-0.1.0.0/reports/1 > > [3]: http://hackage.haskell.org/package/newsynth-0.1.0.0/reports/1/log > > [4]: http://hackage.haskell.org/package/yi-monokai-0.1.1.1/reports/ > > [5]: http://hackage.haskell.org/package/yi-monokai-0.1.1.1/reports/1 > > [6]: > > http://hackage.haskell.org/package/yi-monokai-0.1.1.1/reports/1/log > > [7]: > > > https://github.com/haskell/hackage-server/issues/145#issuecomment-30129142 > > [8]: https://github.com/haskell/hackage-server/issues/142 > > [9]: > > > https://github.com/haskell/hackage-server/issues/145#issuecomment-29468613 > > [10]: https://github.com/haskell/hackage-server/issues/56 > > -- > > Mateusz K. > > > > _______________________________________________ > cabal-devel mailing list > cabal-devel at haskell.org > http://www.haskell.org/mailman/listinfo/cabal-devel > -------------- next part -------------- An HTML attachment was scrubbed... URL: From fuuzetsu at fuuzetsu.co.uk Mon Jan 6 22:55:29 2014 From: fuuzetsu at fuuzetsu.co.uk (Mateusz Kowalczyk) Date: Mon, 06 Jan 2014 22:55:29 +0000 Subject: Broken documentation on Hackage. In-Reply-To: <52C930C3.4080800@fuuzetsu.co.uk> References: <52C930C3.4080800@fuuzetsu.co.uk> Message-ID: <52CB3461.2020101@fuuzetsu.co.uk> On 05/01/14 10:15, Mateusz Kowalczyk wrote: > 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: > > [snip] > > [1]: https://github.com/haskell/hackage-server/issues/145 > [2]: > https://github.com/haskell/hackage-server/issues/145#issuecomment-29468613 > [3]: > https://github.com/haskell/hackage-server/issues/145#issuecomment-29422332 > [4]: http://hackage.haskell.org/packages/trustees/ > [5]: http://fuuzetsu.co.uk/misc/sorted.txt > [6]: > https://github.com/haskell/hackage-server/issues/145#issuecomment-30129142 > [7]: > https://github.com/haskell/hackage-server/issues/145#issuecomment-29472445 > Greetings again, After some feedback from people over yesterday and some digging today, few things became apparent: * cross-package linking is broken with manual documentation * ?Contents? link takes you somewhere else now * I said ?cd dist/doc? instead of ?cd dist/doc/html? Here is what you can do to fix the package links and contents page: add the following flags to the ?cabal haddock? command: --html-location='http://hackage.haskell.org/package/$pkg/docs' --contents-location='http://hackage.haskell.org/package/$pkg' I'm not sure of implication of this for specific version package links. Note also that you do need to put in ?$pkg?, that is a cabal directive. As usual, I welcome any comments and improvements. -- Mateusz K. From simon at joyful.com Mon Jan 6 23:08:55 2014 From: simon at joyful.com (Simon Michael) Date: Mon, 06 Jan 2014 15:08:55 -0800 Subject: Broken documentation on Hackage. In-Reply-To: <52CB3461.2020101@fuuzetsu.co.uk> References: <52C930C3.4080800@fuuzetsu.co.uk> <52CB3461.2020101@fuuzetsu.co.uk> Message-ID: Mateusz, thanks for the great sleuth work and communication on this. I'm working on fixing my missing docs (hledger*, broken due to pretty-show requiring a newer-than-default happy executable). From selinger at mathstat.dal.ca Tue Jan 7 01:23:09 2014 From: selinger at mathstat.dal.ca (Peter Selinger) Date: Mon, 6 Jan 2014 21:23:09 -0400 (AST) Subject: Broken documentation on Hackage. In-Reply-To: <52CB3461.2020101@fuuzetsu.co.uk> Message-ID: <20140107012309.76E118C017C@chase.mathstat.dal.ca> Thanks, that's even better! However, I find that the --contents-location option to cabal haddock does not work properly. Apparently it not only prevents index.html from being built (which makes modest sense), but it also prevents index-frames.html from being built (which does not). So in the frames view, one of the frames will just say "Sorry, it's just not here". That's not very nice. Also, if one loads the "/frames.html" URL directly, it still points to the non-existing index.html, rather than the one given by --contents-location. I think these are bugs. For example, see http://hackage.haskell.org/package/yi-monokai-0.1.1.1/docs/Yi-Style-Monokai.html and click on "Frames". One workaround is to run "cabal haddock" twice: first without the --contents-location option, and then with it. Slightly annoying, but it works. It has the disadvantage that if one goes directly to the ".../frames.html" URL, one will still see the old index.html. Another workaround is to omit the --contents-location option altogether, and to manually create an index.html that is just a forward to the correct location, i.e.: If your browser does not take you there automatically, please go to http://hackage.haskell.org/package/newsynth-0.1.0.0. Only this last solution seems to do the correct thing all the time. For an example, see http://hackage.haskell.org/package/newsynth-0.1.0.0/docs/frames.html Your instructions have been *very* helpful. But it's a lot of details and finnicky cabal directives to keep track of for doing this all the time. I've turned your instructions into a Makefile to automate this task; see attached. In principle, only the first two lines should need to be customized. Then "make doc-upload" will build the documentation and upload it correctly. I know, Cabal somehow was supposed to make Makefiles obsolete. Alas. Fortunately, the Makefile is only for the package maintainer, and not for the package user. -- Peter Mateusz Kowalczyk wrote: > > On 05/01/14 10:15, Mateusz Kowalczyk wrote: > > 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: > > > > [snip] > > > > [1]: https://github.com/haskell/hackage-server/issues/145 > > [2]: > > https://github.com/haskell/hackage-server/issues/145#issuecomment-29468613 > > [3]: > > https://github.com/haskell/hackage-server/issues/145#issuecomment-29422332 > > [4]: http://hackage.haskell.org/packages/trustees/ > > [5]: http://fuuzetsu.co.uk/misc/sorted.txt > > [6]: > > https://github.com/haskell/hackage-server/issues/145#issuecomment-30129142 > > [7]: > > https://github.com/haskell/hackage-server/issues/145#issuecomment-29472445 > > > > Greetings again, > > After some feedback from people over yesterday and some digging today, > few things became apparent: > * cross-package linking is broken with manual documentation > * ?Contents? link takes you somewhere else now > * I said ?cd dist/doc? instead of ?cd dist/doc/html? > > Here is what you can do to fix the package links and contents page: > add the following flags to the ?cabal haddock? command: > > --html-location='http://hackage.haskell.org/package/$pkg/docs' > --contents-location='http://hackage.haskell.org/package/$pkg' > > I'm not sure of implication of this for specific version package links. > Note also that you do need to put in ?$pkg?, that is a cabal directive. > > As usual, I welcome any comments and improvements. > -- > Mateusz K. > _______________________________________________ > cabal-devel mailing list > cabal-devel at haskell.org > http://www.haskell.org/mailman/listinfo/cabal-devel > -------------- next part -------------- A non-text attachment was scrubbed... Name: Makefile Type: application/octet-stream Size: 1569 bytes Desc: Makefile URL: From fuuzetsu at fuuzetsu.co.uk Tue Jan 7 02:28:17 2014 From: fuuzetsu at fuuzetsu.co.uk (Mateusz Kowalczyk) Date: Tue, 07 Jan 2014 02:28:17 +0000 Subject: Broken documentation on Hackage. In-Reply-To: <20140107012309.76E118C017C@chase.mathstat.dal.ca> References: <20140107012309.76E118C017C@chase.mathstat.dal.ca> Message-ID: <52CB6641.2000907@fuuzetsu.co.uk> On 07/01/14 01:23, Peter Selinger wrote: > Thanks, that's even better! > > However, I find that the --contents-location option to cabal haddock > does not work properly. Apparently it not only prevents index.html > from being built (which makes modest sense), but it also prevents > index-frames.html from being built (which does not). So in the frames > view, one of the frames will just say "Sorry, it's just not here". > That's not very nice. Also, if one loads the "/frames.html" URL > directly, it still points to the non-existing index.html, rather than > the one given by --contents-location. I think these are bugs. > > For example, see > http://hackage.haskell.org/package/yi-monokai-0.1.1.1/docs/Yi-Style-Monokai.html > and click on "Frames". Ah, I do not use frames so I did not notice. > One workaround is to run "cabal haddock" twice: first without the > --contents-location option, and then with it. Slightly annoying, but > it works. It has the disadvantage that if one goes directly to the > ".../frames.html" URL, one will still see the old index.html. > > Another workaround is to omit the --contents-location option > altogether, and to manually create an index.html that is just a > forward to the correct location, i.e.: > > > If your browser does not take you there automatically, please go to > http://hackage.haskell.org/package/newsynth-0.1.0.0. > > Only this last solution seems to do the correct thing all the time. > For an example, see > http://hackage.haskell.org/package/newsynth-0.1.0.0/docs/frames.html > > Your instructions have been *very* helpful. But it's a lot of details > and finnicky cabal directives to keep track of for doing this all the > time. I've turned your instructions into a Makefile to automate this > task; see attached. In principle, only the first two lines should need > to be customized. Then "make doc-upload" will build the documentation > and upload it correctly. That looks very useful but I have a few questions about it: * Why a Makefile as opposed to a Bash script or something? I don't think there's a way to pass arguments into a Makefile like to Bash scripts, save for environmental variables. I'd much rather prefer a command line flag for a script in my PATH rather than having to change the file each time. * This file makes us change the top two lines (user and package name) and uses ?read? for everything else. Why not fully go with one way or the other? Personally, I'd prefer arguments rather than ?read? (much easier to repeat commands/script against) but it's up to personal taste. * Can we not grab to project name from the cabal file just like you do with version? * Your ?--html-location? has ?$$pkg? in it, how come? Is that some kind of escape? * Considering you seem to know what you're doing much more than I am, is there any way to detect cabal sandboxes? I'm trying your makefile now (running with make -f /tmp/Makefile doc-upload) and it's giving me an error: ``` [snip] Haddock coverage: 100% ( 18 / 18) in 'Yi.Style.Monokai' Documentation created: dist/doc/html/yi-monokai/index.html rm -r yi-monokai-0.1.1.1-docs rm: cannot remove ?yi-monokai-0.1.1.1-docs?: No such file or directory make: *** [yi-monokai-0.1.1.1-docs.tar.gz] Error 1 ``` It works fine if I comment out the ?rm -r?. Perhaps that should be allowed to fail somehow. > I know, Cabal somehow was supposed to make Makefiles obsolete. Alas. > Fortunately, the Makefile is only for the package maintainer, and not > for the package user. > > -- Peter I think that cabal-install should really have the option to do all this rather than have people write up scripts like this, resulting in trial and error. -- Mateusz K. From carter.schonwald at gmail.com Tue Jan 7 02:42:12 2014 From: carter.schonwald at gmail.com (Carter Schonwald) Date: Mon, 6 Jan 2014 21:42:12 -0500 Subject: Broken documentation on Hackage. In-Reply-To: <52CB6641.2000907@fuuzetsu.co.uk> References: <20140107012309.76E118C017C@chase.mathstat.dal.ca> <52CB6641.2000907@fuuzetsu.co.uk> Message-ID: agreed, cabal-install should definitely get support for doing this correctly added in. (since this is going to become a common activity for maintainers who's libs need extra things installed that the doc builders lack) Any volunteers? On Mon, Jan 6, 2014 at 9:28 PM, Mateusz Kowalczyk wrote: > On 07/01/14 01:23, Peter Selinger wrote: > > Thanks, that's even better! > > > > However, I find that the --contents-location option to cabal haddock > > does not work properly. Apparently it not only prevents index.html > > from being built (which makes modest sense), but it also prevents > > index-frames.html from being built (which does not). So in the frames > > view, one of the frames will just say "Sorry, it's just not here". > > That's not very nice. Also, if one loads the "/frames.html" URL > > directly, it still points to the non-existing index.html, rather than > > the one given by --contents-location. I think these are bugs. > > > > For example, see > > > http://hackage.haskell.org/package/yi-monokai-0.1.1.1/docs/Yi-Style-Monokai.html > > and click on "Frames". > > Ah, I do not use frames so I did not notice. > > > One workaround is to run "cabal haddock" twice: first without the > > --contents-location option, and then with it. Slightly annoying, but > > it works. It has the disadvantage that if one goes directly to the > > ".../frames.html" URL, one will still see the old index.html. > > > > Another workaround is to omit the --contents-location option > > altogether, and to manually create an index.html that is just a > > forward to the correct location, i.e.: > > > > > > If your browser does not take you there automatically, please go to > > > http://hackage.haskell.org/package/newsynth-0.1.0.0. > > > > Only this last solution seems to do the correct thing all the time. > > For an example, see > > http://hackage.haskell.org/package/newsynth-0.1.0.0/docs/frames.html > > > > Your instructions have been *very* helpful. But it's a lot of details > > and finnicky cabal directives to keep track of for doing this all the > > time. I've turned your instructions into a Makefile to automate this > > task; see attached. In principle, only the first two lines should need > > to be customized. Then "make doc-upload" will build the documentation > > and upload it correctly. > > That looks very useful but I have a few questions about it: > * Why a Makefile as opposed to a Bash script or something? I don't > think there's a way to pass arguments into a Makefile like to Bash > scripts, save for environmental variables. I'd much rather prefer a > command line flag for a script in my PATH rather than having to change > the file each time. > > * This file makes us change the top two lines (user and package name) > and uses ?read? for everything else. Why not fully go with one way or > the other? Personally, I'd prefer arguments rather than ?read? (much > easier to repeat commands/script against) but it's up to personal taste. > > * Can we not grab to project name from the cabal file just like you do > with version? > > * Your ?--html-location? has ?$$pkg? in it, how come? Is that some > kind of escape? > > * Considering you seem to know what you're doing much more than I am, > is there any way to detect cabal sandboxes? > > I'm trying your makefile now (running with make -f /tmp/Makefile > doc-upload) and > it's giving me an error: > > ``` > [snip] > Haddock coverage: > 100% ( 18 / 18) in 'Yi.Style.Monokai' > Documentation created: dist/doc/html/yi-monokai/index.html > rm -r yi-monokai-0.1.1.1-docs > rm: cannot remove ?yi-monokai-0.1.1.1-docs?: No such file or directory > make: *** [yi-monokai-0.1.1.1-docs.tar.gz] Error 1 > ``` > > It works fine if I comment out the ?rm -r?. Perhaps that should be > allowed to fail somehow. > > > I know, Cabal somehow was supposed to make Makefiles obsolete. Alas. > > Fortunately, the Makefile is only for the package maintainer, and not > > for the package user. > > > > -- Peter > > I think that cabal-install should really have the option to do all > this rather than have people write up scripts like this, resulting in > trial and error. > > -- > Mateusz K. > _______________________________________________ > cabal-devel mailing list > cabal-devel at haskell.org > http://www.haskell.org/mailman/listinfo/cabal-devel > -------------- next part -------------- An HTML attachment was scrubbed... URL: From selinger at mathstat.dal.ca Tue Jan 7 04:07:11 2014 From: selinger at mathstat.dal.ca (Peter Selinger) Date: Tue, 7 Jan 2014 00:07:11 -0400 (AST) Subject: Broken documentation on Hackage. In-Reply-To: <52CB6641.2000907@fuuzetsu.co.uk> Message-ID: <20140107040712.010D68C017C@chase.mathstat.dal.ca> Hi Mateusz, of course you could do the same thing with a bash script. It's a matter of personal taste and workflow. Just for the record, you can pass arguments into a Makefile like this: "make PACKAGE=bla". And "$$" is indeed an escape, to denote a literal dollar sign (as opposed to a Makefile variable). Sorry about the bug. It should be "rm -rf". I'm not sure about the wisdom of adding new functionality to cabal-install just to compensate for bugs in the Hackage documentation builder. It seems that the packages build correctly everywhere else, so there is no reason in principle why the Hackage documentation builder could not be fixed to build them. I see the manual uploading as more of a temporary workaround. As for the bug with --contents-location and frames, it doesn't come up in the Hackage documentation builder because it apparently disables frames. There must be another (undocumented?) option for turning frames off. -- Peter Mateusz Kowalczyk wrote: > > > Your instructions have been *very* helpful. But it's a lot of details > > and finnicky cabal directives to keep track of for doing this all the > > time. I've turned your instructions into a Makefile to automate this > > task; see attached. In principle, only the first two lines should need > > to be customized. Then "make doc-upload" will build the documentation > > and upload it correctly. > > That looks very useful but I have a few questions about it: > * Why a Makefile as opposed to a Bash script or something? I don't > think there's a way to pass arguments into a Makefile like to Bash > scripts, save for environmental variables. I'd much rather prefer a > command line flag for a script in my PATH rather than having to change > the file each time. > * This file makes us change the top two lines (user and package name) > and uses ?read? for everything else. Why not fully go with one way or > the other? Personally, I'd prefer arguments rather than ?read? (much > easier to repeat commands/script against) but it's up to personal taste. > > * Can we not grab to project name from the cabal file just like you do > with version? > > * Your ?--html-location? has ?$$pkg? in it, how come? Is that some > kind of escape? > > * Considering you seem to know what you're doing much more than I am, > is there any way to detect cabal sandboxes? > > I'm trying your makefile now (running with make -f /tmp/Makefile > doc-upload) and > it's giving me an error: > > ``` > [snip] > Haddock coverage: > 100% ( 18 / 18) in 'Yi.Style.Monokai' > Documentation created: dist/doc/html/yi-monokai/index.html > rm -r yi-monokai-0.1.1.1-docs > rm: cannot remove ?yi-monokai-0.1.1.1-docs?: No such file or directory > make: *** [yi-monokai-0.1.1.1-docs.tar.gz] Error 1 > ``` > > It works fine if I comment out the ?rm -r?. Perhaps that should be > allowed to fail somehow. > > > I know, Cabal somehow was supposed to make Makefiles obsolete. Alas. > > Fortunately, the Makefile is only for the package maintainer, and not > > for the package user. > > > > -- Peter > > I think that cabal-install should really have the option to do all > this rather than have people write up scripts like this, resulting in > trial and error. From dave.laing.80 at gmail.com Thu Jan 9 12:31:15 2014 From: dave.laing.80 at gmail.com (David Laing) Date: Thu, 9 Jan 2014 22:31:15 +1000 Subject: Cabal hack night suggestions In-Reply-To: References: Message-ID: Hi, The hack night has been and gone. It was fun, but I felt I probably could have been more productive. I've found some possibly closeable bugs and some possibly duplicate bugs. Possibly closeable: - 291 - 760 Possible duplicate / at least related: - 469 and 1100 - 172, 674, 1550 - 189, 510, 527, 1585 I got partway through working on #674 before I found #1550 and saw that work is being done there. There are a few bugs / enhancements I'm keen to have a go at, but I'll take that part of the discussion to github. Cheers, Dave On Mon, Jan 6, 2014 at 10:53 PM, Johan Tibell wrote: > Hi David, > > Great to here that you're going to hack on cabal. We need all the > contributors we can get! > > The general roadmap for 1.20 is here: > http://www.haskell.org/pipermail/cabal-devel/2013-September/009533.html > > The "Do the right thing automatically" section is probably the most > newbie friendly. > > Other than that we really need to get the bug tracker under control. This > means triaging bugs and fixing those that need fixing and closing the rest. > I took a stab at this a while ago but if you want something to get your > feet wet, I suggest grabbing something that looks interesting from the bug > tracker. > > As for hacking on cabal, I suggest using sandboxes, like so: > > cd cabal/cabal-install > # only once: > cabal sandbox init > cabal sandbox add-source ../Cabal > cabal install -j --only-dep > # to (re)build: > cabal build > > -- Johan > > > On Fri, Jan 3, 2014 at 1:50 PM, David Laing wrote: > >> Hi all, >> >> There are a few people in my local FP meetup group looking into doing >> some semi-regular Haskell hack nights, and we're hoping to target various >> tools and libraries in the Haskell ecosystem so that we can give back a >> little while having fun and honing our skills. >> >> Cabal is pretty high on our list of things to hack on, and we're hoping >> to start mid next week. >> >> I'm sure we'll be able to click through github issues and submit pull >> requests on our own, but I thought I'd ask if anyone has any thoughts on >> areas that would be good to look at that might sit in a sweet spot of being >> both beneficial to Cabal and accessible to newcomers to the code. >> >> Does anyone have any thoughts? >> >> Cheers, >> >> Dave >> >> _______________________________________________ >> cabal-devel mailing list >> cabal-devel at haskell.org >> http://www.haskell.org/mailman/listinfo/cabal-devel >> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: From johan.tibell at gmail.com Thu Jan 9 12:57:29 2014 From: johan.tibell at gmail.com (Johan Tibell) Date: Thu, 9 Jan 2014 13:57:29 +0100 Subject: Cabal hack night suggestions In-Reply-To: References: Message-ID: Hi David, Thanks for the bug triage, I will definitely take a look at those. Let me know if there's anything I can do to make it a more productive session next time. Cheers, Johan On Thu, Jan 9, 2014 at 1:31 PM, David Laing wrote: > Hi, > > The hack night has been and gone. It was fun, but I felt I probably could > have been more productive. > > I've found some possibly closeable bugs and some possibly duplicate bugs. > > Possibly closeable: > - 291 > - 760 > Possible duplicate / at least related: > - 469 and 1100 > - 172, 674, 1550 > - 189, 510, 527, 1585 > > I got partway through working on #674 before I found #1550 and saw that > work is being done there. > > There are a few bugs / enhancements I'm keen to have a go at, but I'll > take that part of the discussion to github. > > Cheers, > > Dave > > > On Mon, Jan 6, 2014 at 10:53 PM, Johan Tibell wrote: > >> Hi David, >> >> Great to here that you're going to hack on cabal. We need all the >> contributors we can get! >> >> The general roadmap for 1.20 is here: >> http://www.haskell.org/pipermail/cabal-devel/2013-September/009533.html >> >> The "Do the right thing automatically" section is probably the most >> newbie friendly. >> >> Other than that we really need to get the bug tracker under control. This >> means triaging bugs and fixing those that need fixing and closing the rest. >> I took a stab at this a while ago but if you want something to get your >> feet wet, I suggest grabbing something that looks interesting from the bug >> tracker. >> >> As for hacking on cabal, I suggest using sandboxes, like so: >> >> cd cabal/cabal-install >> # only once: >> cabal sandbox init >> cabal sandbox add-source ../Cabal >> cabal install -j --only-dep >> # to (re)build: >> cabal build >> >> -- Johan >> >> >> On Fri, Jan 3, 2014 at 1:50 PM, David Laing wrote: >> >>> Hi all, >>> >>> There are a few people in my local FP meetup group looking into doing >>> some semi-regular Haskell hack nights, and we're hoping to target various >>> tools and libraries in the Haskell ecosystem so that we can give back a >>> little while having fun and honing our skills. >>> >>> Cabal is pretty high on our list of things to hack on, and we're hoping >>> to start mid next week. >>> >>> I'm sure we'll be able to click through github issues and submit pull >>> requests on our own, but I thought I'd ask if anyone has any thoughts on >>> areas that would be good to look at that might sit in a sweet spot of being >>> both beneficial to Cabal and accessible to newcomers to the code. >>> >>> Does anyone have any thoughts? >>> >>> Cheers, >>> >>> Dave >>> >>> _______________________________________________ >>> cabal-devel mailing list >>> cabal-devel at haskell.org >>> http://www.haskell.org/mailman/listinfo/cabal-devel >>> >>> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: