Document how to cache stack

[philderbeast]

How should we set up this action to cache stack, like cabal with caching. Here's the caching for liquid-fixpoint:

      - name: Cache ~/.stack and .stack-work
        uses: actions/cache@v3
        with:
          path: |
            ~/.stack
            .stack-work
          key: ${{ runner.os }}-${{ matrix.ghc }}-stack-${{ hashFiles('**/*.cabal', './stack.yaml', './stack.yaml.lock') }}

[andreasabel]

I asked the Stack tsar about advice but did not get anything definitive:

• Blessed recipe how to use stack on github actions, in particular caching? commercialhaskell/stack#5754

Some points:

1. Cache key: I could not get Stack to dump me the complete build plan (all dependencies with versions) for a project (unlike Cabal, which has the plan.json). Theoretically, the build plan should be the resolver + stack.yaml (which contains the resolver). So your key seems to be a best effort solution. (I never understood the significance or the .lock file in the cache key, can it be dropped?)
2. Cache size (global): caching the whole STACK_ROOT ~/.stack can be forbiddingly expensive (GB size), so one cannot have many cache instances with the default 10GB limit. Cited issue (see above) describes how to just cache parts of the STACK_ROOT. However, I have some conceptual questions whether this is possible (as the directory is basically a database).
3. Cache size (local): the .stack-work directory can also be very big. Also, e.g. for Agda it did not prevent total recompilation of the project (maybe because of timestamps). So, one can consider not caching it at all.

[philderbeast]

1. I could not get Stack to dump me the complete build plan (all dependencies with versions) for a project

Could we get stack to list the dependencies and key off that?

$ stack ls dependencies text
...
utf8-string 1.0.2
...

$ stack ls dependencies json | jq > stack-deps.json
$ cat stack-deps.json
[
...
  {
    "dependencies": [
      "base",
      "bytestring"
    ],
    "license": "BSD3",
    "location": {
      "type": "hackage",
      "url": "https://hackage.haskell.org/package/utf8-string-1.0.2"
    },
    "name": "utf8-string",
    "version": "1.0.2"
  },
...
]

[andreasabel]

Interesting, the build plan (dependencies) is hidden under the innocuous stack ls which otherwise let's you see which colors stack uses on the terminal (stack-colors), an empty list (tools), or a list of useless hashes (snapshots).
Certainly not where I would go looking for it...

[philderbeast]

Interesting, the build plan (dependencies) is hidden under the innocuous stack ls
...
Certainly not where I would go looking for it...

@andreasabel could you please relate this experience of command nesting making dependencies harder to find on the thread about targets? There you suggested nesting targets under a cabal list command, haskell/cabal#9744 (comment). I think that cabal targets should be a top-level command. Do you now too?

[TravisCardwell]

When listing dependencies, --system-ghc is necessary to prevent Stack from installing GHC. It looks like the following argument order works:

stack --system-ghc ls dependencies json

[TravisCardwell]

FYI: Here is a related discussion on Haskell Discourse: Github cache action

[ulidtko]

Subscribing here.

BTW, the ${{ runner.os }}- portion of cache-key is unnecessary: github's actions/cache has cross-os cache sharing as an opt-in feature — which means it's off by default — thus caches aren't shared across runner OS's by default. Thus having runner.os in the key has no effect.

I also talked a lot more about caching keys in the post Andreas linked above.