contributing: add implicit-hie gen-hie > hie.yaml note

[Anton-Latukha]

On my setups, the gen-hie tool was found to be irreplaceable.

Mainline documentation currently directs people to read lengthy HLS docs on cradle & then directs reading HIE-Bios docs on it & says to make all hie.yaml by hand. For every project person wants to contribute to.

& currently that means:

cradle:
  cabal:
    - path: "./ghcide/src"
      component: "lib:ghcide"

    - path: "./ghcide/session-loader"
      component: "lib:ghcide"

    - path: "./ghcide/test/preprocessor/Main.hs"
      component: "ghcide:exe:ghcide-test-preprocessor"

    - path: "./ghcide/bench/hist/Main.hs"
      component: "ghcide:bench:benchHist"

    - path: "./ghcide/bench/lib/Main.hs"
      component: "ghcide:bench:benchHist"

    - path: "./ghcide/bench/hist/Experiments/Types.hs"
      component: "ghcide:bench:benchHist"

    - path: "./ghcide/bench/lib/Experiments/Types.hs"
      component: "ghcide:bench:benchHist"

    - path: "./ghcide/exe/Main.hs"
      component: "ghcide:exe:ghcide"

    - path: "./ghcide/exe/Arguments.hs"
      component: "ghcide:exe:ghcide"

    - path: "./ghcide/test/cabal"
      component: "ghcide:test:ghcide-tests"

    - path: "./ghcide/test/exe"
      component: "ghcide:test:ghcide-tests"

    - path: "./ghcide/test/src"
      component: "ghcide:test:ghcide-tests"

    - path: "./ghcide/bench/lib"
      component: "ghcide:test:ghcide-tests"

    - path: "./ghcide/bench/lib/Main.hs"
      component: "ghcide:exe:ghcide-bench"

    - path: "./ghcide/bench/exe/Main.hs"
      component: "ghcide:exe:ghcide-bench"

    - path: "./ghcide/test/src/Main.hs"
      component: "ghcide:exe:ghcide-bench"

    - path: "./ghcide/bench/lib/Development/IDE/Test/Diagnostic.hs"
      component: "ghcide:exe:ghcide-bench"

    - path: "./ghcide/bench/lib/Experiments.hs"
      component: "ghcide:exe:ghcide-bench"

    - path: "./ghcide/bench/lib/Experiments/Types.hs"
      component: "ghcide:exe:ghcide-bench"

    - path: "./ghcide/bench/exe/Development/IDE/Test/Diagnostic.hs"
      component: "ghcide:exe:ghcide-bench"

    - path: "./ghcide/bench/exe/Experiments.hs"
      component: "ghcide:exe:ghcide-bench"

    - path: "./ghcide/bench/exe/Experiments/Types.hs"
      component: "ghcide:exe:ghcide-bench"

    - path: "./ghcide/test/src/Development/IDE/Test/Diagnostic.hs"
      component: "ghcide:exe:ghcide-bench"

    - path: "./ghcide/test/src/Experiments.hs"
      component: "ghcide:exe:ghcide-bench"

    - path: "./ghcide/test/src/Experiments/Types.hs"
      component: "ghcide:exe:ghcide-bench"

    - path: "./src"
      component: "lib:haskell-language-server"

    - path: "./exe/Main.hs"
      component: "haskell-language-server:exe:haskell-language-server"

    - path: "./exe/Plugins.hs"
      component: "haskell-language-server:exe:haskell-language-server"

    - path: "./exe/Wrapper.hs"
      component: "haskell-language-server:exe:haskell-language-server-wrapper"

    - path: "./test/functional"
      component: "haskell-language-server:test:func-test"

    - path: "./test/utils"
      component: "haskell-language-server:test:func-test"

    - path: "./test/wrapper"
      component: "haskell-language-server:test:wrapper-test"

    - path: "./hie-compat/src-ghc86"
      component: "lib:hie-compat"

    - path: "./hie-compat/src-ghc88"
      component: "lib:hie-compat"

    - path: "./hie-compat/src-reexport"
      component: "lib:hie-compat"

    - path: "./hie-compat/src-ghc810"
      component: "lib:hie-compat"

    - path: "./hie-compat/src-reexport"
      component: "lib:hie-compat"

    - path: "./hie-compat/src-reexport-ghc9"
      component: "lib:hie-compat"

    - path: "./hie-compat/src-reexport-ghc9"
      component: "lib:hie-compat"

    - path: "./hls-graph/src"
      component: "lib:hls-graph"

    - path: "./hls-plugin-api/src"
      component: "lib:hls-plugin-api"

    - path: "./hls-test-utils/src"
      component: "lib:hls-test-utils"

    - path: "./plugins/hls-brittany-plugin/src"
      component: "lib:hls-brittany-plugin"

    - path: "./plugins/hls-brittany-plugin/test"
      component: "hls-brittany-plugin:test:tests"

    - path: "./plugins/hls-call-hierarchy-plugin/src"
      component: "lib:hls-call-hierarchy-plugin"

    - path: "./plugins/hls-call-hierarchy-plugin/test"
      component: "hls-call-hierarchy-plugin:test:tests"

    - path: "./plugins/hls-class-plugin/src"
      component: "lib:hls-class-plugin"

    - path: "./plugins/hls-class-plugin/test"
      component: "hls-class-plugin:test:tests"

    - path: "./plugins/hls-eval-plugin/src"
      component: "lib:hls-eval-plugin"

    - path: "./plugins/hls-eval-plugin/test"
      component: "hls-eval-plugin:test:tests"

    - path: "./plugins/hls-explicit-imports-plugin/src"
      component: "lib:hls-explicit-imports-plugin"

    - path: "./plugins/hls-explicit-imports-plugin/test"
      component: "hls-explicit-imports-plugin:test:tests"

    - path: "./plugins/hls-floskell-plugin/src"
      component: "lib:hls-floskell-plugin"

    - path: "./plugins/hls-floskell-plugin/test"
      component: "hls-floskell-plugin:test:tests"

    - path: "./plugins/hls-fourmolu-plugin/src"
      component: "lib:hls-fourmolu-plugin"

    - path: "./plugins/hls-fourmolu-plugin/test"
      component: "hls-fourmolu-plugin:test:tests"

    - path: "./plugins/hls-haddock-comments-plugin/src"
      component: "lib:hls-haddock-comments-plugin"

    - path: "./plugins/hls-haddock-comments-plugin/test"
      component: "hls-haddock-comments-plugin:test:tests"

    - path: "./plugins/hls-hlint-plugin/test"
      component: "hls-hlint-plugin:test:tests"

    - path: "./plugins/hls-module-name-plugin/src"
      component: "lib:hls-module-name-plugin"

    - path: "./plugins/hls-module-name-plugin/test"
      component: "hls-module-name-plugin:test:tests"

    - path: "./plugins/hls-ormolu-plugin/src"
      component: "lib:hls-ormolu-plugin"

    - path: "./plugins/hls-ormolu-plugin/test"
      component: "hls-ormolu-plugin:test:tests"

    - path: "./plugins/hls-pragmas-plugin/src"
      component: "lib:hls-pragmas-plugin"

    - path: "./plugins/hls-pragmas-plugin/test"
      component: "hls-pragmas-plugin:test:tests"

    - path: "./plugins/hls-refine-imports-plugin/src"
      component: "lib:hls-refine-imports-plugin"

    - path: "./plugins/hls-refine-imports-plugin/test"
      component: "hls-refine-imports-plugin:test:tests"

    - path: "./plugins/hls-rename-plugin/src"
      component: "lib:hls-rename-plugin"

    - path: "./plugins/hls-rename-plugin/test"
      component: "hls-rename-plugin:test:tests"

    - path: "./plugins/hls-retrie-plugin/src"
      component: "lib:hls-retrie-plugin"

    - path: "./plugins/hls-splice-plugin/src"
      component: "lib:hls-splice-plugin"

    - path: "./plugins/hls-splice-plugin/test"
      component: "hls-splice-plugin:test:tests"

    - path: "./plugins/hls-stylish-haskell-plugin/src"
      component: "lib:hls-stylish-haskell-plugin"

    - path: "./plugins/hls-stylish-haskell-plugin/test"
      component: "hls-stylish-haskell-plugin:test:tests"

    - path: "./plugins/hls-tactics-plugin/src"
      component: "lib:hls-tactics-plugin"

    - path: "./plugins/hls-tactics-plugin/test"
      component: "hls-tactics-plugin:test:tests"

While contributor just wants to make project to load into running HLS - to study through the code & be able to navigate the whole project to study how things are done.

Patch advises trying a cradle generator, or using it as possible starting point. It helped me for years in complex project setups. It helped me even in my own projects with complex setups.

[jneira]

Hi, thanks for improving docs. Suggesting the use gen-hie to generate the cradle is nice, in fact we are recommending it in main docs: https://haskell-language-server.readthedocs.io/en/latest/configuration.html#configuring-your-project-build:

You also can use implicit-hie to automatically generate hie.yaml files for the most common stack and cabal configurations

And in the section we are also noting:

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

hls underneath calls implicit-hie to generate on the fly the exactly same config you can see with gen-hie, without needing to create any file. In fact i load hls with no hie.yaml at all, and also the ./install subproject (to be precise the unique subproject in the repo with its own stack.yaml/cabal.project, the rest are subpackages sharing the same stack.yaml/cabal.project)

So i simply would remove the so if you want to work on this part of the code, you may also have to create an install/hie.yaml file. part.

[Anton-Latukha]

New update, taking your note into account.

Since contribution guideline info was outdated - provided restructuring best I could.

I thought that if implicit configuration did not worked - recommend generating & start looking at explicit configuration, that helped me numerous times, people able to read & understand configuration & see what is there & check configuration themselves & it is also way easier to understand & read docs in that way.

I do not know information about implicit stack detection - if it applies or not, so kept it at the end.

Please feel free to actively delete & change any part of the documentation, even directly inside PR - is Ok for documentation workflow.

[Anton-Latukha]

Representation result can be seen at the branch.

[jneira]

Representation result can be seen at the branch.

The final result in readthedocs can be checked in the docs build for the pr (you can navigate through the readthedocs build check): https://haskell-language-server--2341.org.readthedocs.build/en/2341/contributing/contributing.html#using-hls-on-hls-code

[jneira]

Not sure if an error loading the project without explicit hie.yaml will be probable but those steps will be a good guidance in that case, thanks!

[Anton-Latukha]

Yes. From upstream discussion I see that it should work.

But I also previously in recent years personally got assured 3 times by upstream that "implicit configuration should work as is". To make HLS work - in the past I needed to abandon NixOS & so I currently have pretty clean Arch Linux setup worrying to make HLS work & GHCup installed currently recommended by it GHC, Cabal & HLS - & I still had to infer the configuration... Now I recheck -- it probably was remnants from that old recommendation:

cradle:
  cabal:

That is why first thing I put in docs 2 times, implicitly & explicitly - to check & delete the remnants. Old contributor (or previously failed to boot the project person) returning - may be a valid case to keep around until the situation surely stabilizes & people clean up their setups.

But also we never should assume that everything "just works" on all setups. Because I've seen some crazy skilled people with some out their setups, especially inside the Haskell Nix land. Help in debugging & submitting info is helpful.

---

I also feel kinda as a bikeshedding discussing 1 paragraph of docs that much.

I did a lot of bikeshedding in recent 4 years to learn the foundations of Haskell in detail & now have problems switching from refactoring into "good enough" mode & zooming out & be internally accepting of other people styles, but I work on myself.

[Avi-D-coder]

To make HLS work - in the past I needed to abandon NixOS

If you ever run into issues with hls not working in a nix-shell or NixOS give me a shout. The trick is to build hls from source in your nix-shell. It has to be built by the same nix-shell as your project otherwise you'll get linking errors.

[Anton-Latukha]

Not sure if an error loading the project without explicit hie.yaml will be probable but those steps will be a good guidance in that case, thanks!

Well - the situation was unstable for a very long time. & Haskell bootstrapping - there are Cabal, HPack, Backpack mixins inside Cabal, number of Cabal features, Git Worktree, Stack, Nix (NixPkgs, Nix-Shell, Flakes, Haskell.Nix), DHall & people can use mixtures of them ... so people would need debugging help. & would report something from time to time (& I hope as you that implicit config would work for them), but realistically - there are some esoteric setups & often people have reason for them.

[Anton-Latukha]

To make HLS work - in the past I needed to abandon NixOS

If you ever run into issues with hls not working in a nix-shell or NixOS give me a shout. The trick is to build hls from source in your nix-shell. It has to be built by the same nix-shell as your project otherwise you'll get linking errors.

That is what I'm talking about.

I basically abandoned NixOS, to be able to develop Haskell-Nix/HNix, as for me the Haskell development story in NixOS was rough for several years with only windows of opportunity when HLS started to work, during 1/2 a year period & I wrote documentation how to do it & published in Reddit back in a day. Now I also sort of abandoning HNix (that means in time DHall <-> Nix conversion might suffer.) - because nobody except me seems to care about it enough to contribute semi-regularly & keeping-up with Nix & reverse-engineering C++ project is rough. Imagine if GHC updates were even less documented & it was in C++ & HLS in Haskell needed to integrate with it all the time - it somewhere in that area.

[Anton-Latukha]

Thank you for your work.

I hope I would be able to contribute something more valuable in the future.