Tutorial installation instructions didn't work

mjdominus commented 2 years ago

The instructions at https://docs.servant.dev/en/stable/tutorial/install.html failed for me in multiple ways.

cabal-install

The cabal new-build tutorial command failed, saying

      /home/mjd/src/haskell-job/servant/cabal.project:59:
      Parse of field 'allow-newer' failed.

I figured out that this was because the Ubuntu Cabal package is from the stone age and installed cabal-3.4. But it still failed:

Resolving dependencies...
cabal: Could not resolve dependencies:
[__0] trying: cookbook-basic-auth-0.1 (user goal)
[__1] trying: base-4.9.1.0/installed-4.9.1.0 (dependency of
cookbook-basic-auth)
[__2] next goal: servant-auth (user goal)
[__2] rejecting: servant-auth-0.4.1.0 (conflict:
base==4.9.1.0/installed-4.9.1.0, servant-auth => base>=4.10 && <4.16)
[__2] skipping: servant-auth-0.4.0.0 (has the same characteristics that caused
the previous version to fail: excludes 'base' version 4.9.1.0)
[__2] rejecting: servant-auth-0.3.2.0, servant-auth-0.3.1.0,
servant-auth-0.3.0.1, servant-auth-0.3.0.0, servant-auth-0.2.7.0,
servant-auth-0.2.6.1, servant-auth-0.2.6.0, servant-auth-0.2.1.0,
servant-auth-0.2.0.0, servant-auth-0.1.0.1, servant-auth-0.1.0.0 (constraint
from user target requires ==0.4.1.0)
[__2] fail (backjumping, conflict set: base, servant-auth)
After searching the rest of the dependency tree exhaustively, these were the
goals I've had most trouble fulfilling: base, servant-auth,
cookbook-basic-auth

I didn't know how to proceed from there so I moved on to the stack instructions.

stack

The instructions say to do stack new myproj servant. I got this error:

Downloading lts-18.25 build plan ...RedownloadFailed Request {
  host                 = "raw.githubusercontent.com"
  port                 = 443
  secure               = True
  requestHeaders       = []
  path                 = "/fpco/lts-haskell/master//lts-18.25.yaml"
  queryString          = ""
  method               = "GET"
  proxy                = Nothing
  rawBody              = False
  redirectCount        = 10
  responseTimeout      = ResponseTimeoutDefault
  requestVersion       = HTTP/1.1
}
 "/home/mjd/.stack/build-plan/lts-18.25.yaml" (Response {responseStatus = Status {statusCode = 404, statusMessage = "Not Found"}, responseVersion = HTTP/1.1, responseHeaders = [("Connection","keep-alive"),("Content-Length","14"),("Content-Security-Policy","default-src 'none'; style-src 'unsafe-inline'; sandbox"),("Strict-Transport-Security","max-age=31536000"),("X-Content-Type-Options","nosniff"),("X-Frame-Options","deny"),("X-XSS-Protection","1; mode=block"),("Content-Type","text/plain; charset=utf-8"),("X-GitHub-Request-Id","8576:6C91:AEC958:D48EF0:62117EAB"),("Accept-Ranges","bytes"),("Date","Sat, 19 Feb 2022 23:35:07 GMT"),("Via","1.1 varnish"),("X-Served-By","cache-ewr18127-EWR"),("X-Cache","MISS"),("X-Cache-Hits","0"),("X-Timer","S1645313707.372621,VS0,VE68"),("Vary","Authorization,Accept-Encoding,Origin"),("Access-Control-Allow-Origin","*"),("X-Fastly-Request-ID","eac6de468e8caa9cf1b223c412ff01ab7604d49e"),("Expires","Sat, 19 Feb 2022 23:40:07 GMT"),("Source-Age","0")], responseBody = (), responseCookieJar = CJ {expose = []}, responseClose' = ResponseClose})

At this point it's not clear how to proceed. I tried cd'ing to the myproj directory and running stack build as suggested by the next step in the instructions, but the failure was the same.

nix

The instructions here assume that the user already knows what they are doing. I don't, but I tried anyway. I installed Nix on my system and confirmed that the daemon was running and I could run nix-shell. Then I ran nix-shell nix/shell.nix --arg tutorial true which seemed to work: it reported downloading dependencies and it gave me a nix-shell prompt. But it's not clear what to do next.

Additionally

The tutorial docs at https://docs.servant.dev/en/stable/tutorial/install.html say “Copyright 2018”. The doc/tutorial/install.rst file was substantively updated in 2019 at commit d4289931ad69f1233c9f75f230f7bb29650df433, so the copyright ought to be at least 2019.

Thanks; please let me know how I can help you resolve this issue.

mjdominus commented 2 years ago

The basic issue here is that Ubuntu ships with ancient versions of cabal, stack, and ghc. Updating cabal didn't help because ghc was still too old.

I uninstalled the ubuntu cabal, stack, and ghc packages, and used ghcup https://www.haskell.org/ghcup/install/ to install recent versions of everything. After this, the cabal instructions seemed to work. (I didn't try stack.)

I will try to submit a doc patch later today.

alpmestan commented 2 years ago

Reviewed your patch, thanks for taking a bit of time to fix the instructions.

Regarding:

The instructions here assume that the user already knows what they are doing. I don't, but I tried anyway. I installed Nix on my system and confirmed that the daemon was running and I could run nix-shell. Then I ran nix-shell nix/shell.nix --arg tutorial true which seemed to work: it reported downloading dependencies and it gave me a nix-shell prompt. But it's not clear what to do next.

FWIW, IIRC you can just cabal build once in that shell. And also run the doc-related stuffs, e.g make in the doc/ directory.

haskell-servant / servant