How to use Cabal in Windows

[jasagredo]

trafficstars

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 :tm:. I could use some thorough reviews.

[Kleidukos]

@bradrn would you mind taking a look?

[bradrn]

Thanks for the reminder! I’ll read through it later today.

[jasagredo]

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:

1. Install via ghcup. Refer to its documentation.
2. Libraries need to be visible in extra-lib-dirs. Includes need to be visible in extra-include-dirs. Unix tools need to be visible in extra-prog-path. Ghcup takes care of it for you.
3. End

I will try to answer why I chose to write the chunks where questions were asked above.

[bradrn]

1. Install via ghcup. Refer to its documentation.
2. Libraries need to be visible in extra-lib-dirs. Includes need to be visible in extra-include-dirs. Unix tools need to be visible in extra-prog-path. Ghcup takes care of it for you.
3. End

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

[jasagredo]

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

[bradrn]

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!

[jasagredo]

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

[bradrn]

@bradrn I would not mention that it is strongly recommended to use the installations that come with GHCup and Stack.

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.

[jasagredo]

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.

[bradrn]

However it seems this is out of the scope for the Cabal documentation. I might file a ticket to GHCup to mention this then.

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.

[jasagredo]

Cabal requires knowing the location of MSYS2

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.

your latest version strongly recommends using GHCup in the first place

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.

[bradrn]

Cabal requires knowing the location of MSYS2

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.

Aargh, imprecise wording again! Of course, this whole conversation is only relevant if you need to use external packages.

your latest version strongly recommends using GHCup in the first place

It recommends using GHCup to install a Haskell environment.

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]

I have pushed a new version. This time changing the title, moving the line GHCup will install its own MSYS2 system in your computer unless told not to do so, refer to its documentation <https://www.haskell.org/ghcup/install/#windows_1>_ for more information. up and adding links to the global config discovery (thanks @bradrn for that one!).

I also squashed the intermediate commits.

[Mikolaj]

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?

[jasagredo]

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 :smile:

[bradrn]

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.

[philderbeast]

mention Stack too, even if GHCup is strongly recommended.

@mpilgrem what do you recommend? Stack's docs mention GHCup. As a long time Stack user, I prefer having GHCup manage the selected Stack and GHC version (but I'm often switching GHC version).

$ cat ~/.stack/config.yaml
system-ghc: true
install-ghc: false

[mpilgrem]

On 'mentioning Stack', I think it depends on the purpose of the page. If its primary purpose is the use of Cabal (the tool), provided by the cabal-install package, on Windows, I would not expect Stack to feature. If its primary purpose is the use of Cabal (the library) on Windows, then Stack is one way to use that library: all of Stack's building is done using Cabal (the library). Stack's User Guide has a number of references to Cabal (the tool) (I think they are all respectful - I've a 'to do' to ensure that they are accurate and up-to-date).

@philderbeast, system-ghc and install-ghc are only tangentially related to Stack using GHCup to manage versions of GHC. The better reference is: https://docs.haskellstack.org/en/stable/yaml_configuration/#ghc-installation-customisation

In terms of using GHCup (rather than Stack) to manage versions of Stack, I don't embrace that myself - but that is because I am often building Stack from source and stack upgrade will overwrite the GHCup 'shim' executable named stack.

[hasufell]

In terms of using GHCup (rather than Stack) to manage versions of Stack, I don't embrace that myself - but that is because I am often building Stack from source and stack upgrade will overwrite the GHCup 'shim' executable named stack.

We could certainly fix that by providing a ghcup compile stack variant.

[jasagredo]

I spot a few places where phrasing could be slightly improved, but no major issues.

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

[bradrn]

I will be more than happy to fix grammar/phrasing mistakes in this document should you point them out

OK, I’ll add some comments now.

[bradrn]

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]

I have squashed the commits into one. Now only missing piece are approving reviews :+1:

Thanks all!

[Mikolaj]

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)?

[jasagredo]

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.

[Mikolaj]

@mergify backport 3.12

[mergify[bot]]

backport 3.12

✅ Backports have been created

• #9977 How to use Cabal in Windows (backport #9723) has been created for branch 3.12