haskell-servant / haskell-servant/servant

Tutorial installation instructions didn't work

Open
#1,540 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Haskell
Stars
2k
Forks
427
Avg merge
2d 23h
Merged PRs (30d)
5

Description

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.

Contributor guide

Open the contributing guide

Research direction

Start with doc/tutorial/install.rst and compare it with the published installation page. Reproduce the documented cabal-install, stack, and nix steps, then update the instructions so the tutorial has a clear next step after nix-shell and correct the copyright year; done means the documented paths are actionable and the reported failures are addressed.

Written by the indexing model from the issue text.

Assessment

Tech stack
haskell
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.