Create "Getting started" tutorial.

[m-renaud]

Create a Getting Started guide focused on newcomers to the Haskell ecosystem and Cabal. This page sits at the front of the Cabal user guide and walks through creating a new package, building and running it, and adding a dependency on a package from Hackage.

Rendered docs can be found at: https://m-renaud-haskell-cabal.readthedocs.io/en/mrenaud-docs-newcomer-tutorial/getting-started.html

Follow-up PRs:

• Link to cabal (v2-)build docs (when they are written)
• Write and link to section about ^>= (there's no place that really explains it currently)
• More commentary about :target syntax (and write docs discussing target syntax to link to)
• Add section about "projects"

---

Please include the following checklist in your PR:

• Patches conform to the coding conventions.
• Any changes that could be relevant to users have been recorded in the changelog.
• The documentation has been updated, if necessary.
• If the change is docs-only, [ci skip] is used to avoid triggering the build bots.

Please also shortly describe how you tested your change. Bonus points for added tests!

[jneira]

Thanks for writing this, it will be a great improvement for beginners.
One note: it seems to me that, in general, it could be more friendly for windows users:

• Installation method refer to an only *nix method (I know that it redirects to haskell platform but still)
• All console commands are posix, although some of them could be executed in cmd and/or powershell.

Otoh not sure if the tutorial needs some changes to be executed.

I've got an error following the instructions cause the cabal file generated has not the adequate cabal-version with support for the caret operator (i've tried it with 3.0.0.0 and 3.2.0.0):

PS D:\dev\ws\haskell\myapp> cabal-3.0.0.0 run :myapp
Errors encountered when parsing cabal file .\myapp.cabal:

myapp.cabal:24:46: error:
unexpected major bounded version syntax (caret, ^>=) used. To use this syntax the package need to specify at least 'cabal-version: 2.0'. Alternatively, if broader compatibility is important then use: >=1.0.0.0 && <1.1
expecting "." or "-"

   23 |   build-depends:       base >=4.12 && <4.13,
   24 |                        haskell-say ^>=1.0.0.0
      |                                              ^

I am getting errors with the target for cabal-3.2.0.0 (is it a cabal bug??!?) and the lib haskell-say is not in hackage (i suppose it will be before pushing this to master):
NOTE: i've done a cabal update, the lib is already in hackage (i did the last one yesterday, It is still hot)

PS D:\dev\ws\haskell\myapp> cabal-3.2.0.0 run :myapp
cabal-3.2.0.0.exe: Unrecognised target ':myapp'.
Expected a meta-target 'all', rather than 'myapp'.

PS D:\dev\ws\haskell\myapp> cabal-3.0.0.0 run :myapp # same for cabal-3.2.0.0 run all
Build profile: -w ghc-8.6.5 -O1
In order, the following will be built (use -v for more details):
 - myapp-0.1.0.0 (exe:myapp) (first run)
Preprocessing executable 'myapp' for myapp-0.1.0.0..
Building executable 'myapp' for myapp-0.1.0.0..
[1 of 1] Compiling Main             ( Main.hs, D:\dev\ws\haskell\myapp\dist-newstyle\build\x86_64-windows\ghc-8.6.5\myapp-0.1.0.0\x\myapp\build\myapp\myapp-tmp\Main.o )
Linking D:\dev\ws\haskell\myapp\dist-newstyle\build\x86_64-windows\ghc-8.6.5\myapp-0.1.0.0\x\myapp\build\myapp\myapp.exe ...
  ________________________________________________________
 /                                                        \
| Hello, Haskell! You're using a function from another     |
| package!                                                 |
 \____       _____________________________________________/
      \    /
       \  /
        \/
  _____   _____
   \    \  \    \
    \    \  \    \
     \    \  \    \  \-----------|
      \    \  \    \  \          |
       \    \  \    \  \---------|
       /    /  /     \
      /    /  /       \  \-------|
     /    /  /    ^    \  \      |
    /    /  /    / \    \  \ ----|
   /    /  /    /   \    \
  /____/  /____/     \____\

[phadej]

As I commented, we should rather collect what we can simplify once 3.4 is released in a separate issue, but write the guide with 3.2 in mind. Then this will be useful immediately.

[jneira]

Yeah, i guessed it would work with latest version.
But i would try to make the guide retrocompatible as much as possible, without adding nothing about to be obsolete or introduce any complexity. I would use cabal-3.0 if there is no strong reasons to disallow it, but 3.2 would be nice too. The guide must note the required version of cabal in a visible place.

F.e. the caret operator is great but simply changing the example to be

executable myfirstapp
       main-is: Main.hs
       build-depends:
           base >=4.11 && <4.12,
           haskell-say >=1.0.0.0 && < 1.1

You could remove the note about the caret operator and it would look simpler (more uniform) and it would be compatible with cabal-3.0 at once.
Hopefully users will be able to discover the caret operator later.

[phadej]

cabal-install-3.0 supports caret operator as nicely. The cabal-version: 2.4 is the important part in the generated .cabal file itself.

Hopefully users will be able to discover the caret operator later.

They won't. It's safer to assume that they won't read beyond Getting started if things just work.

[jneira]

Mmm, yeah, cabal supports it even before, but cabal-3.0 init by default does not generate a .cabal file compatible, and without the caret operator cabal init --cabal-version=2.4 would not be needed, but it is fine.

They won't. It's safer to assume that they won't read beyond Getting started if things just work.

Fair enough.

[m-renaud]

Hey @jneira, thanks for the feedback!

Installation method refer to an only *nix method ...

Added a link to a Windows walkthrough for getting Haskell set up.

All console commands are posix, although some of them could be executed in cmd and/or powershell.

tbh I haven't used Windows in years, is there anything specific I should change here?

...cabal-version with support for the caret operator...

Yeah, oops, I had forgotten that the change to switch cabal inits Cabal spec version to 2.4 isn't in a release yet, updated instructions to pass --cabal-version=2.4 explicitly.

[phadej]

Related to your previous comment. I think it would be actually good to find some library which has few transitive dependencies.

[m-renaud]

I was thinking that in a (yet to be written) walkthrough on working with multiple packages in a project is where we could pull in more deps, wanted to keep this as simple as possible.

[phadej]

it's not about multiple packages. It's about showing that cabal-install does work for you. You don't have to worry (as a beginner) if a dependency has own dependencies, it just works :)

I'm irritated by recent article where is recommended to shave your dependencies to the minimum. No, use your own common sense.

[jneira]

ls would work in powershell, in dos we have to use dir (the output will be different in any case but whatever)

[phadej]

It looks like that if we ask windows users to use PowerShell than there're only small tweaks needed? casing for cmd would make it all too messy and hard to follow.

[jneira]

yeah, powershell is fine nowadays imo, it is even the default console in windows 10 (and available in previous versions)

[m-renaud]

Added some words about it working on unix shells and PowerShell if you're a Windows user.