[Documentation] new project setup

[KristianBalaj]

It is hard to find out how to make the plugin work for a beginner.

I needed to check out my previous projects to find out that I need to create a hie.yaml file with following lines to make the plugin work.

cradle:
  cabal:
    - path: './src'
      component: 'proj:exe:proj'

This should be written in the plugin documentation.

[jneira]

hi @KristianBalaj, thanks for your report. This plugin is closely related with the haskell-language-server, the lsp server which provides almost all features.
There we have some docs about configuring each piece: the editor, the server, your haskell project: https://haskell-language-server.readthedocs.io/en/latest/configuration.html#configuring-your-project-build

There we can read:

At the moment, haskell-language-server has support to automatically detect your project build configuration to handle most use cases.

So using a explicit hie.yaml file will not likely fix your ide setup. It will do it almost only if you see an error like Multi Cradle: No prefixes matched

So maybe we should make more discoverable the server docs from the extension.

Otoh does your project not work if you dont have that hie-yaml file?

[jneira]

So maybe we should make more discoverable the server docs from the extension.

The repo of haskell-language-server is linked in the first paragraph but what could we add in the readme to make clearer the association?

[KristianBalaj]

Otoh does your project not work if you dont have that hie-yaml file?

Yup, the plugin was not working for me until I've added the hie.yaml. After that the intellisense started to work.

The repo of haskell-language-server is linked in the first paragraph but what could we add in the readme to make clearer the association?

Yeah, It didn't even come to me, to go to that link. The first setup I've done was searching through different Haskell repos and trying to add different configurations that I've found in the repos 😄
I would certainly add some lines to the start of the plugin documentation on how to make the plugin work ad hoc.

Proposal

In my opinion, I would move the Requirements section to the top of the readme right on top of the Features section and I would rename it to Installation, Setup, Enabling or Quick Start, it's your pick.
Also, this can be seen in multiple mainstream plugins (Python, Javascript, etc...) because it is the most important to make it work.
Additionaly, the quick start guide should be added there to make an empty cabal project work.
Like following:

1. Check that you have cabal and ghc installed with following commands ...
2. run cabal init --interactive in the current directory
3. Add hie.yaml with following contents ..... (not sure if this is the correct step)
4. etc...

And for someone who needs more configuration options, I would explicitly link the most important sections in the haskell-language-server repo.

[jneira]

Yup, the plugin was not working for me until I've added the hie.yaml. After that the intellisense started to work.

As stated in the hls docs the unique issue a explicit hie.yaml it is supposed to fix is the Multi Cradle: No prefixes matched error. And most project cabal configs does not throw it. So maybe another factor could fix the hls setup

Could you reproduce the error consistently deleting the hie.yaml (doing a succesful cabal clean && cabal build before open the project in the editor)?
If it is reproduced, could you link or describe the project config and post the log of calling haskell-language-server-wrapper -d in the project root directory?
thanks in advance!

Proposal
....

Many thanks for suggesions, they make sense. Would you like and have time to make a pr following them?

[KristianBalaj]

@jneira after deleting the hie.yaml and doing cabal clean && cabal build while VS Code closed the Multi Cradle: No prefixes matched is there after opening the VS Code.
But the intellisense works ¯\_(ツ)_/¯

Fyi. the haskell has a clean install from yesterday via ghcup.

ghcup tui

┌─────────────────────────────────────GHCup────────────────────────────────────┐
│    Tool  Version         Tags                          Notes                 │
│──────────────────────────────────────────────────────────────────────────────│
│✔✔  GHCup 0.1.17.2        latest,recommended                                  │
│──────────────────────────────────────────────────────────────────────────────│
│✔✔  Stack 2.7.3           latest,recommended                                  │
│──────────────────────────────────────────────────────────────────────────────│
│✔✔  HLS   1.4.0           latest,recommended                                  │
│✗   HLS   1.3.0                                                               │
│──────────────────────────────────────────────────────────────────────────────│
│✗   cabal 3.6.2.0         latest                                              │
│✔✔  cabal 3.4.1.0         recommended                                         │
│──────────────────────────────────────────────────────────────────────────────│
│✗   GHC   9.2.0.20210821  prerelease,base-4.16.0.0                            │
│✗   GHC   9.0.1           latest,base-4.15.0.0          hls-powered           │
│✔✔  GHC   8.10.7          recommended,base-4.14.3.0     hls-powered           │
│✗   GHC   8.8.4           base-4.13.0.0                 hls-powered           │
│✗   GHC   8.6.5           base-4.12.0.0                 hls-powered           │
│✗   GHC   8.4.4           base-4.11.1.0                                       │
│                                                                              │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

haskell-language-server-wrapper -d

No 'hie.yaml' found. Try to discover the project type!
Run entered for haskell-language-server-wrapper(haskell-language-server-wrapper) Version 1.4.0.0, Git revision 253547816ee216c53ee7dacc0ad3cac43e863d30 (dirty) x86_64 ghc-8.10.4
Current directory: /Users/kristian/Documents/Kristian/haskell/vocabulary_proj
Operating system: darwin
Arguments: ["-d"]
Cradle directory: /Users/kristian/Documents/Kristian/haskell/vocabulary_proj
Cradle type: Cabal

Tool versions found on the $PATH
cabal:          3.4.1.0
stack:          2.7.3
ghc:            8.10.7


Consulting the cradle to get project GHC version...
Project GHC version: 8.10.7
haskell-language-server exe candidates: ["haskell-language-server-8.10.7","haskell-language-server"]
Launching haskell-language-server exe at:/Users/kristian/.ghcup/bin/haskell-language-server-8.10.7
haskell-language-server version: 1.4.0.0 (GHC: 8.10.7) (PATH: /Users/kristian/.ghcup/bin/haskell-language-server-8.10.7~1.4.0) (GIT hash: 253547816ee216c53ee7dacc0ad3cac43e863d30)
 ghcide setup tester in /Users/kristian/Documents/Kristian/haskell/vocabulary_proj.
Report bugs at https://github.com/haskell/haskell-language-server/issues

Step 1/4: Finding files to test in /Users/kristian/Documents/Kristian/haskell/vocabulary_proj
Found 1 files

Step 2/4: Looking for hie.yaml files that control setup
Found 1 cradle
  ()

Step 3/4: Initializing the IDE
2021-10-25 11:12:42.074105 [ThreadId 7] DEBUG hls:      Initializing exports map from hiedb
2021-10-25 11:12:42.076003 [ThreadId 7] DEBUG hls:      Done initializing exports map from hiedb (8)

Step 4/4: Type checking the files
2021-10-25 11:12:42.758878 [ThreadId 42] DEBUG hls:     hlint:getIdeas:file:NormalizedFilePath "/Users/kristian/Documents/Kristian/haskell/vocabulary_proj/src/Main.hs"
2021-10-25 11:12:42.760078 [ThreadId 44] INFO hls:      Consulting the cradle for "src/Main.hs"
2021-10-25 11:12:42.760209 [ThreadId 44] WARNING hls:   No [cradle](https://github.com/mpickering/hie-bios#hie-bios) found for src/Main.hs.
 Proceeding with [implicit cradle](https://hackage.haskell.org/package/implicit-hie).
You should ignore this message, unless you see a 'Multi Cradle: No prefixes matched' error.
Output from setting up the cradle Cradle {cradleRootDir = "/Users/kristian/Documents/Kristian/haskell/vocabulary_proj", cradleOptsProg = CradleAction: Cabal}
2021-10-25 11:12:42.770033 [ThreadId 44] DEBUG hls:     Session loading result: Left [CradleError {cradleErrorDependencies = [], cradleErrorExitCode = ExitSuccess, cradleErrorStderr = ["Multi Cradle: No prefixes matched","pwd: /Users/kristian/Documents/Kristian/haskell/vocabulary_proj","filepath: /Users/kristian/Documents/Kristian/haskell/vocabulary_proj/src/Main.hs","prefixes:","(\"app/Main.hs\",Cabal {component = Just \"vocabulary-proj:exe:vocabulary-proj\"})"]}]
2021-10-25 11:12:42.771114 [ThreadId 41] INFO hls:      File:     /Users/kristian/Documents/Kristian/haskell/vocabulary_proj/src/Main.hs
Hidden:   no
Range:    1:1-2:1
Source:   cradle
Severity: DsError
Message: 
  Multi Cradle: No prefixes matched
  pwd: /Users/kristian/Documents/Kristian/haskell/vocabulary_proj
  filepath: /Users/kristian/Documents/Kristian/haskell/vocabulary_proj/src/Main.hs
  prefixes:
  ("app/Main.hs",Cabal {component = Just "vocabulary-proj:exe:vocabulary-proj"})
2021-10-25 11:12:42.772206 [ThreadId 54] INFO hls:      finish: User TypeCheck (took 0.01s)
2021-10-25 11:12:42.772413 [ThreadId 57] INFO hls:      finish: GetHie (took 0.00s)
Files that failed:
 * /Users/kristian/Documents/Kristian/haskell/vocabulary_proj/src/Main.hs

Completed (0 files worked, 1 file failed)
2021-10-25 11:12:42.772506 [ThreadId 59] INFO hls:      finish: GenerateCore (took 0.00s)
haskell-language-server-wrapper: callProcess: /Users/kristian/.ghcup/bin/haskell-language-server-8.10.7 "-d" (exit 1): failed

[jneira]

@jneira after deleting the hie.yaml and doing cabal clean && cabal build while VS Code closed the Multi Cradle: No prefixes matched is there after opening the VS Code.

hmm could you share your .cabal file?

[jneira]

In my opinion, I would move the Requirements section to the top of the readme right on top of the Features section

Actually i am not sure of this one: if you already are sure you want the extension cause you has used it maybe you want to know how to make it work first.
But if you are evaluating if you are gonna use vscode for haskell or what extension to use (there are a bunch of them) maybe features will be more interesting

If requirements continue to be short, features would be still visible but if we extends it they will be out of the visible area.

Additionaly, the quick start guide should be added there to make an empty cabal project work.

And for someone who needs more configuration options, I would explicitly link the most important sections in the haskell-language-server repo.

Totally agree in those ones

[jneira]

Also, this can be seen in multiple mainstream plugins (Python, Javascript, etc...) because it is the most important to make it work.

In the rust extension i can see the features in the first place (without demos) and the quick start in a second position, out of the visible area in my screen.

I use rust as example cause it is a relatively less popular language like haskell and we usually use it as model in other areas (f.e. rustup was the main inspiration for ghcup).

[KristianBalaj]

Sure! Here it goes

Cabal file

cabal-version:      2.4
name:               vocabulary-proj
version:            0.1.0.0

-- A short (one-line) description of the package.
-- synopsis:

-- A longer description of the package.
-- description:

-- A URL where users can report bugs.
-- bug-reports:

-- The license under which the package is released.
-- license:
author:             Kristián Balaj
maintainer:         kiko.balaj@gmail.com

-- A copyright notice.
-- copyright:
-- category:
extra-source-files: CHANGELOG.md


executable vocabulary-proj
    main-is:          Main.hs
    hs-source-dirs: src

    -- Modules included in this executable, other than Main.
    -- other-modules:

    -- LANGUAGE extensions used by modules in this package.
    -- other-extensions:
    build-depends:
        base ^>=4.14.3.0,
        text,
        fmt

    hs-source-dirs:   app
    default-language: Haskell2010

Note 1

Sorry, tried the intellisense again, it is actually not working ✋

[jneira]

mmm I think the cause of the issue is the duplicate hs-source-dirs, if you remove the last one it should work without hie.yaml

[KristianBalaj]

Features before requirements .....

Yeah sure, it's your choice. I agree that extending the requirements will make the features invisible.

But you could at least add a link to the requirements above the features to highlight it.

[KristianBalaj]

mmm I think the cause of the issue is the duplicate hs-source-dirs, if you remove the last one it should work without hie.yaml

Yup my bad, it's working now.

One related issue to the project setup

When I make the cabal init in an empty directory and open the Main.hs. The VS Code shows a notification Project requires GHC but it isn't installed.
And the plugin is not working at all ¯\_(ツ)_/¯ - no intellisense there.