Plugin tutorial, more changes (#4570)

* Plugin tutorial, more changes

Some changes are mine, but many have been cherry picked and amended from
PR #3655 by Christian Georgii <cgeorgii@gmail.com>.

* Update Nix Flake lock (this makes GHC 9.8 the default)

* Review comments and other improvments, thanks @VeryMilkyJoe.

* Compile plugin-tutorial using markdown-unlit

Makes sure the plugin-tutorial can never be out-of-date again.

* Remove out-of-date references

* Add plugin-tutorial to CI

* Only build the plugin-tutorial with GHC 9.6 and 9.8

* Add explanation for preamble

---------

Co-authored-by: fendor <fendor@posteo.de>

Author: dschrempf

.github/workflows/test.yml

@@ -255,6 +255,12 @@ jobs:
         name: Test hls-notes-plugin test suite
         run: cabal test hls-notes-plugin-tests || cabal test hls-notes-plugin-tests
 
+      # The plugin tutorial is only compatible with 9.6 and 9.8.
+      # No particular reason, just to avoid excessive CPP.
+      - if: matrix.test && matrix.ghc != '9.4' && matrix.ghc != '9.10' && matrix.ghc != '9.12'
+        name: Compile the plugin-tutorial
+        run: cabal build plugin-tutorial
+
   test_post_job:
     if: always()
     runs-on: ubuntu-latest

docs/contributing/plugin-tutorial.lhs

@@ -0,0 +1 @@
+plugin-tutorial.md

docs/contributing/plugin-tutorial.md

@@ -225,6 +225,7 @@ module Development.IDE.GHC.Compat.Core (
     SrcLoc.noSrcSpan,
     SrcLoc.noSrcLoc,
     SrcLoc.noLoc,
+    SrcLoc.srcSpanToRealSrcSpan,
     mapLoc,
     -- * Finder
     FindResult(..),

flake.lock

@@ -2265,3 +2265,28 @@ test-suite ghcide-bench-test
         OverloadedStrings
         RecordWildCards
         ViewPatterns
+
+executable plugin-tutorial
+  import: defaults
+  -- The plugin tutorial is only compatible with 9.6 and 9.8.
+  -- No particular reason, just to avoid excessive CPP.
+  if (impl(ghc >= 9.6) && impl(ghc < 9.10))
+    buildable: True
+  else
+    buildable: False
+  ghc-options: -pgmL markdown-unlit
+  main-is: docs/contributing/plugin-tutorial.lhs
+  build-tool-depends: markdown-unlit:markdown-unlit
+  build-depends:
+    base,
+    ghcide,
+    hls-plugin-api,
+    aeson,
+    lsp,
+    lsp-types,
+    markdown-unlit,
+    text,
+    unordered-containers,
+    containers,
+    transformers,
+    ghc,

ghcide/src/Development/IDE/GHC/Compat/Core.hs

@@ -121,15 +121,13 @@ import           GHC                                               (AddEpAnn (Ad
                                                                     EpaLocation,
                                                                     EpaLocation' (..),
                                                                     HasLoc (..))
-import           GHC.Types.SrcLoc                                  (srcSpanToRealSrcSpan)
 #endif
 #if MIN_VERSION_ghc(9,11,0)
 import           GHC                                               (EpaLocation,
                                                                     AnnsModule (am_where),
                                                                     EpaLocation' (..),
                                                                     HasLoc (..),
                                                                     EpToken (..))
-import           GHC.Types.SrcLoc                                  (srcSpanToRealSrcSpan)
 #endif