Skip to content

Latest commit

 

History

History
184 lines (149 loc) · 12 KB

README.md

File metadata and controls

184 lines (149 loc) · 12 KB

Stack Action

GitHub Action to build and test a stack-based Haskell project.

Usage

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: freckle/stack-action@v5

Notable Changes in v5

As of version 5, the single stack-arguments input has been broken up into various, distinct stack-[*-]arguments[-*] inputs that are used in more specific ways. See the Inputs section, or action.yml for documentation of the new options.

The fast and pedantic inputs were removed. Use a ternary operator (see Operators) to pass a flag conditionally. Example:

stack-build-arguments: ${{ github.ref_name != 'main' && '--fast' || '' }} --pedantic

Notable Changes in v4

As of version 4, this action automatically handles caching. You do not need to use a separate stack-cache-action step any more.

Notable Changes in v3

Previous versions of this Action ran HLint and Weeder for you. We recommend doing that as separate actions now, so, as of v3, those options have been removed.

Here is an example of running separate Actions:

jobs:
  test:
    # ...
    steps:
      - uses: actions/checkout@v4
      - id: stack
        uses: freckle/stack-action@v5

      # Weeder requires running in the same Job (to access .hie artifacts)
      - uses: freckle/weeder-action@v2
        with:
          ghc-version: ${{ steps.stack.outputs.compiler-version }}

  # HLint can be a distinct Job, possibly limited to changed files
  hlint:
    # ...
    steps:
      - uses: actions/checkout@v4
      - uses: haskell-actions/hlint-setup@v1
      - uses: haskell-actions/hlint-run@v2

Inputs

name description required default
working-directory

Working directory for run commands

false ""
test

Whether to run tests

false true
stack-arguments

Additional arguments for all top-level stack command invocations.

false --no-terminal
stack-query-arguments

Additional arguments in stack query invocations.

false ""
stack-path-arguments

Additional arguments in stack path invocations.

false ""
stack-setup-arguments

Additional arguments in stack setup invocations.

false ""
stack-build-arguments

Additional arguments for all stack build invocations.

false --fast --pedantic
stack-build-arguments-dependencies

Additional arguments passed after stack-build-arguments in stack build invocations on the Dependencies step.

false ""
stack-build-arguments-build

Additional arguments passed after stack-build-arguments in stack build invocations on the Build step.

false ""
stack-build-arguments-test

Additional arguments passed after stack-build-arguments in stack build invocations on the Test step.

false ""
cache-prefix

Prefix applied to all cache keys. This can be any value you like, but teams often use v{N} and bump it to v{N+1} when/if they need to explicitly bust caches.

false ""
cache-save-always

Save artifacts to the cache even if the build fails. This may speed up builds in subsequent runs at the expense of slightly-longer builds when a full cache-hit occurs. Since @v4.2.0.

false false
on-dirty-files

What to do if we find changes to the cabal or lock file after a build. Value can be warn, or error. Default is warn.

false warn
install-stack

Install stack, if necessary

false true
upgrade-stack

Upgrade stack

false true
compiler-tools

A list of packages to install as compiler tools, one per line. This is useful to do here rather than separate run commands so that their installation is incorporated in the dependency cache. Since @v5.2.0.

false ""
stack-yaml

Deprecated use env.STACK_YAML or stack-arguments instead.

false ""

Outputs

name description
compiler

compiler.actual value from stack query

compiler-version

The GHC version part of compiler

snapshot-doc-root

snapshot-doc-root value from stack path

local-doc-root

local-doc-root value from stack path

local-hoogle-root

local-hoogle-root value from stack path

stack-root

stack-root value from stack path

project-root

project-root value from stack path

config-location

config-location value from stack path

bin-path

bin-path value from stack path

programs

programs value from stack path

compiler-exe

compiler-exe value from stack path

compiler-bin

compiler-bin value from stack path

compiler-tools-bin

compiler-tools-bin value from stack path

local-bin

local-bin value from stack path

extra-include-dirs

extra-include-dirs value from stack path

extra-library-dirs

extra-library-dirs value from stack path

snapshot-pkg-db

snapshot-pkg-db value from stack path

local-pkg-db

local-pkg-db value from stack path

global-pkg-db

global-pkg-db value from stack path

ghc-package-path

ghc-package-path value from stack path

snapshot-install-root

snapshot-install-root value from stack path

local-install-root

local-install-root value from stack path

dist-dir

dist-dir value from stack path

local-hpc-root

local-hpc-root value from stack path

Installing Compiler Tools

The compiler-tools input can be used to install packages (with --copy-compiler-tool) as part of the Dependencies step. The installed tools can be used by other parts of the build via stack exec, such as to reformat and upload coverage:

- id: stack
  uses: freckle/stack-action@v5
  with:
    compiler-tools: hpc-lcov
    stack-build-arguments: --coverage

- run: stack --no-terminal exec -- hpc-lcov --file "$HPC_ROOT"/combined/all/all.tix
  env:
    HPC_ROOT: ${{ steps.stack.outputs.local-hpc-root }}

- uses: codecov/codecov-action@v2
  with:
    files: ./lcov.info

Doing it this way, vs a separate run: stack install..., means the building of these tools will be included in the dependencies cache.

Generating a Build Matrix of stack.yamls

The following automatically discovers all files matching stack*.yaml and runs this action with each of them:

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - id: generate
        uses: freckle/stack-action/generate-matrix@v5
    outputs:
      stack-yamls: ${{ steps.generate.outputs.stack-yamls }}

  test:
    needs: generate
    strategy:
      matrix:
        stack-yaml: ${{ fromJSON(needs.generate.outputs.stack-yamls) }}
      fail-fast: false

    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: freckle/stack-action@v5
        with:
          stack-arguments: --stack-yaml ${{ matrix.stack-yaml }}

See generate-matrix/action.yml for more details. This has been available since version 4 of this action.


LICENSE