How to use Cabal in Windows #9723
Conversation
There was a problem hiding this comment.
I'm not on the Cabal team and I haven't used Windows for years, but this feels important enough that I didn't want it to sit unreviewed. It's great that you wrote this, and I think with a bit of focusing on the intended reader, it'll be a very useful addition to the manual.
Overall, I think it's important to keep the main reader of this document in mind: someone who has just installed Haskell (probably through GHCup) and needs to get cabal working. They will be very frustrated if things appear to work but then mysterious msys failures cause breakage the first time they build a package that wants to run a ./configure script or do unixy things.
I think information which supports that goal should come first, and each section can drill into the details as much as is necessary. I get the sense that this PR contains a lot of hard-won knowledge; while it's good to have those details written down somewhere, I believe the main reader of a document like this will want to just get cabal going (and may drill down if things aren't working right).
|
@bradrn would you mind taking a look? |
|
Thanks for the reminder! I’ll read through it later today. |
There was a problem hiding this comment.
In general, I'm mildly skeptical of the current version of this PR.
I do not like the idea that cabal documentation provides extensive information about how GHCup does things, how to install it and run it. That is in the GHCup documenation. Let's please keep things separate.
In addition, I find this is quite verbose and the main information (adding things to extra-include-dirs, extra-lib-dirs and extra-prog-path) is way too far down.
The information about adjusting PATH I consider incorrect.
There was a problem hiding this comment.
Just read through this document. In general, I agree with @hasufell: this is overly long, poorly structured, covers many extraneous details, and contains some recommendations which may be actively harmful. To me, it reads more like ‘my recommendations for using Haskell on Windows’, rather than something which can be included in Cabal documentation.
However, I think it’s salvageable. I may try to condense this into a shorter and more focussed guide, then make my own PR.
EDIT: To make myself clear, I don’t think this is a bad document necessarily. It would make a fine standalone article. It’s just that it’s wider in scope than is necessary for Cabal-specific documentation.
|
I tried to build up the information step by step, first with GHC alone then with cabal. I think that although it is at the end of the document, a user first checks the list of subsections, at least that is what I would do. I kind of prefer to be extra verbose, explain too many things but still have things explained somewhere. I'm unaware of a resource that tells you how to use Haskell on Windows, the closest thing is GHC wiki pages which are either outdated or talk only about how to build GHC alone on windows. However if one doesn't feel that way, I can see how this can be seen as too verbose and overly specific for the Cabal documentation. I will trim it down. In terms of Documentation relevant to Cabal, I'm unsure then what to mention. I propose the following:
I will try to answer why I chose to write the chunks where questions were asked above. |
I don’t think GHCup should be described at all, except insofar as the docs need to mention that it might provide an MSYS2 installation. GHCup-specific stuff goes in GHCup’s documentation. (Which already has a Windows section, incidentally, but it needs expansion.) |
|
@bradrn @hasufell @endgame First of all, kindly thank you for your reviews. I have pushed another commit that fully re-does the document, this time limiting myself to mention the things that seem relevant to "what do I need to do to run Cabal on windows". I omitted side explanations on why are things as they are or giving context on what is being used underneath and why. I hope this looks more suitable for the Cabal documentation. |
|
As it happens, I’ve been working on my own version of this document. I’m no longer going to submit it as its own PR, since I believe @jasagredo’s new version is superior. However, if there’s anything I’ve written there which looks useful to integrate into this PR, feel free to copy it over! |
|
@bradrn I would not mention that it is strongly recommended to use the installations that come with GHCup and Stack. If a user only wants to do Haskell on their machine then maybe, but what if you want to install an editor such as Emacs by compiling it in MSYS2? Or do work in some other language? Must I be using the GHCup MSYS2? I don't think so. |
I meant, of course, for Haskell-specific work. I assumed that was clear from context. What I’d like to avoid is the situation where someone installs GHCup, then sees that it can integrate with MSYS2 so they go and install MSYS2 separately. The end result is that they’ve mistakenly ended up with an MSYS2 installation which GHCup doesn’t know about, which could get confusing. |
|
Indeed. That is what I tried to explain before by saying that GHCup can work with an existing MSYS2 and trying to outline how to do so. However it seems this is out of the scope for the Cabal documentation. I might file a ticket to GHCup to mention this then. In general my previous write up assumed that the general user is not only going to do Haskell work in Windows, hence why I focused on providing instructions that would work for an existing MSYS2. But as you say, this is probably not the context in which Haskell is used or what is expected from the Cabal documentation. It seems Haskell/Cabal should try to isolate as much as possible from other tools or developer practices. |
This would be a good idea. I think it’s at least fair to mention in the Cabal documentation that Cabal requires knowing the location of MSYS2, and describe some places where it might be found. I mean, for that matter, your latest version strongly recommends using GHCup in the first place. If that’s acceptable, then I think my recommendations certainly should be too. |
This is only true if you happen to need something from MSYS2. If you are only compiling packages which do not rely on external tools then you don't need an MSYS2. So Cabal doesn't require knowing this. In fact it is the User the one that wants cabal to know these.
It recommends using GHCup to install a Haskell environment. I chose deliberately to defer the question about "what if I already have an MSYS2 installation?" to GHCup's documentation where it seems this should be mentioned. I tried to explain it here but this was widely rejected. To be clear I'm not saying that I recommend using GHCup's MSYS2. I might need to make this clear in the document but I don't know how to do so without stepping over what is said to be GHCup's business. |
Aargh, imprecise wording again! Of course, this whole conversation is only relevant if you need to use external packages.
Yes, that’s what I was referring to. To me this seems a far stronger (and less relevant) statement than ‘use GHCup/Stack’s MSYS2 environment, if you’re using GHCup/Stack’. |
jasagredo
force-pushed
the
js/how-to-windows
branch
from
8f67086
to
c732a3d
Compare
|
I have pushed a new version. This time changing the title, moving the line I also squashed the intermediate commits. |
|
Dear all, can we move this forward? @jasagredo: what do you need from us at this point? More comments? Reviews? Formal review acceptance? All of the above? |
|
I think I have addressed all the comments that arose during the reviews. I'm happy to expand this document a bit more if wanted, but I would need to know which directions should I expand it towards (debugging errors maybe?) although these could also be done in a follow-up PR. So I think what I need is basically formal approvals, although reviews (even without approval) are also more than welcome 😄 |
|
At a quick skim, this looks OK. Later today when I get time, I’ll read through it more carefully. (Ping me if I forget!) One initial comment: in the first section it may be a good idea to mention Stack too, even if GHCup is strongly recommended. |
We could certainly fix that by providing a |
I'm not a native English speaker so my phrasing sometimes is not 100% correct. I will be more than happy to fix grammar/phrasing mistakes in this document should you point them out, or I happily would accept commits into this branch or a PR or something like that |
OK, I’ll add some comments now. |
|
I think it’s all fine now. GitHub says it needs two approving reviews, but after that it’s ready to be merged (in my opinion). |
jasagredo
force-pushed
the
js/how-to-windows
branch
from
79ec5e1
to
0709350
Compare
|
I have squashed the commits into one. Now only missing piece are approving reviews 👍 Thanks all! |
jasagredo
force-pushed
the
js/how-to-windows
branch
from
0709350
to
7030037
Compare
|
Shall we backport this to 3.12, since this only expands (and plausibly fixes) documentation? I assume it does not describe anything that is on master branch, but not the 3.12 branch (which is master from 1 or 2 months ago)? |
|
These are purely additions to the documentation, and the behavior described has not changed for a long time, so it is applicable to 3.12 (even to older versions). So if possible, backporting it would be nice. |
|
@mergify backport 3.12 |
✅ Backports have been created
|
mergify
bot
added
the
merge delay passed
How to use Cabal in Windows (backport #9723)
This is my humble attempt at providing some documentation for how to use GHC and Cabal in Windows. It aims to resolve #9713 , however all I wrote here is based on my experience and might not be The Correct Way To Do Things ™️. I could use some thorough reviews.