[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:         [email protected]

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

[jneira]

if you open a file instead a directory hls will not use cabal to load the file but directly ghc so it needs it in PATH (as noted in the requirements)
does it happen when you open the project root directory? or does it happen even if you have ghc in path?

[jneira]

does it happen when you open the project root directory? or does it happen even if you have ghc in path?

If that is the case maybe you have to source you .bashrc in you .profile (used for windows based applications)
See haskell/haskell-language-server#236

[KristianBalaj]

Yeah I have all the things on my PATH. I'm using MacOS.

The reproduction steps to the mentioned issue are:

1. Have the VS Code closed
2. Run the cabal init from a terminal in an empty directory
3. Open the directory in the VS Code and the mentioned error notification shows up

This actually doesn't happen when the cabal init is called from a terminal from the VS Code.

[jneira]

This actually doesn't happen when the cabal init is called from a terminal from the VS Code.

hmm interesting, do you see some diff in the .cabal or cabal.project files generated by cabal init between both cases?
maybe restarting (closing and opening it again) vscode after cabal init in the vscode embedded terminal makes it work?

[KristianBalaj]

Well, I've tried this mupltiple times but this issue looks somehow non-deterministic 😄

The error notification is displayed non-deterministically. There is no difference between the projects from my point of view.
Yup in some cases restarting the VS Code made it work, but sometimes, it does not help and I can't make the plugin work 🤔
Sometimes the project starts to work, but sometimes it does not.
The only solution seems to purge the project and try to call cabal install until the project starts to work.

In case you would like to see some logs, do not hesitate to ping me. It is in my interest to make the plugin work cleanly.

[jneira]

Thanks for checking it, maybe it worths to open a new issue about (and left this one for docs improvements about getting started) here or in the hls repo as i am not sure if the issue is client or server specific.
It would be great to have a reproducible set of steps but it would not be essential so dont hesitate in opening it.

The haskell lsp logs (in the output pane of vscode) from both cases will help too.

[KristianBalaj]

@jneira I was going to open up an issue regarding the missing GHC popup.

When I was digging into the issue deeper I've found out that I was starting the VS Code from a /bin/bash shell where the GHC was not on the PATH instead of the /bin/zsh where the GHC was on the PATH.
So I'm not opening the issue since it is resolved.

EDIT: I was wrong once again, I was actually opening it from the correct shell. Opening the issue.