> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# haskell-works/haskell-build

Builds a Haskell application using cabal v2-*.

## Commands

### add-private-hackage-repo

If configured, add a repository in ~/.cabal/config

| Parameter | Type | Default | Description |
|---|---|---|---|
| `private-hackage-domain` | string |  | FQDN of private hackage repo. |
| `private-hackage-keys` | string |  | Root keys for private hackage repo. |
| `private-hackage-password` | string |  | Password on private hackage repo. |
| `private-hackage-user` | string |  | Username on private hackage repo. |

### build-with-binary-cache

Perforks build using cabal-cache

| Parameter | Type | Default | Description |
|---|---|---|---|
| `after-build` | steps |  | Optional steps to run after build but before running tests |
| `after-test` | steps |  | Optional steps to run after executing unit tests |
| `before-build` | steps |  | Optional steps to run after cabal update but before build |
| `binary-cache-opts` | string |  | AWS log level |
| `binary-cache-region` | string |  | Binary cache region.  This is one of the AWS regions. |
| `binary-cache-threads` | string |  | Number of threads for uploaded and downloading binary cache. |
| `binary-cache-uri` | string |  | Binary cache URI.  This may be an S3 URI. |
| `binary-cache-uri-suffix` | string |  | Binary cache URI suffix.  This defaults to empty.  When supplied the binary cache URI will be
extended to include the suffix via simple concatenation.
 |
| `build-components` | string |  | Component names to build ("all" by default) |
| `build-components-separately` | boolean | false | Build specified components separately |
| `build-documentation` | boolean |  | Build Haddock documentation that can be uploaded to Hackage |
| `cabal-build-extra` | string |  | Extra CLI parameters to pass to the "cabal v2-build" command. |
| `cabal-cache-tag` | string |  | Cabal cache tag |
| `cabal-cache-uri` | string | ${CABAL_CACHE_URI} | Cabal cache URI.  The location of the cabal-cache binary to download. |
| `cabal-test-extra` | string |  | Extra CLI parameters to pass to the "cabal v2-test" command. |
| `cabal-threads` | integer |  | Number of Cabal threads. |
| `cache-version` | string |  | Cache version. Update this value when you want to start with new build caches. |
| `fail-incoherent-builds` | boolean |  | Fail the build when immediate dependencies are incoherent |
| `github-token` | string | ${GITHUB_TOKEN} | Github OAuth2 token to use when making Github API requests |
| `run-check` | boolean |  | Boolean for whether or not to check if the package has valid cabal file for distribution |
| `run-tests` | boolean |  | Boolean for whether or not to run unit tests |
| `test-no-output-timeout` | integer | 600 | No output timeout for tests |

### build-with-cci-cache

Perform build using CCI built-in cache

| Parameter | Type | Default | Description |
|---|---|---|---|
| `after-build` | steps |  | Optional steps to run after build but before running tests |
| `after-test` | steps |  | Optional steps to run after executing unit tests |
| `before-build` | steps |  | Optional steps to run after cabal update but before build |
| `build-components` | string |  | Component names to build ("all" by default) |
| `build-components-separately` | boolean | false | Build specified components separately |
| `build-dependencies-first` | boolean |  | Build project first with "--dependencies-only".
This is useful for making sure that dependencies are cached even if the priject doesn't compile,
but can get in a way in some situations.
 |
| `build-documentation` | boolean |  | Build Haddock documentation that can be uploaded to Hackage |
| `cabal-build-extra` | string |  | Extra CLI parameters to pass to the "cabal v2-build" command. |
| `cabal-test-extra` | string |  | Extra CLI parameters to pass to the "cabal v2-test" command. |
| `cabal-threads` | integer |  | Number of Cabal threads. |
| `cache-version` | string |  | Cache version. Update this value when you want to start with new build caches. |
| `fail-incoherent-builds` | boolean |  | Fail the build when immediate dependencies are incoherent |
| `run-check` | boolean |  | Boolean for whether or not to check if the package has valid cabal file for distribution |
| `run-tests` | boolean |  | Boolean for whether or not to run unit tests |
| `test-no-output-timeout` | integer | 600 | No output timeout for tests |

### cabal-check-all

Run cabal check for all projects in the repository

### capture-build-environment

Capturing build environment (for caching)

| Parameter | Type | Default | Description |
|---|---|---|---|
| `cache-version` | string |  | Cache version. Update this value when you want to start with new build caches. |

### check-immediate-dependencies-coherence

Check if --enable-test and --enable-benchmark are safe to use

### copy-bin

| Parameter | Type | Default | Description |
|---|---|---|---|
| `workspace-dir` | string |  | Result workspace directory name |

### describe-build

Describes the build by providing info for all the local components in this build

### install-cabal-cache

| Parameter | Type | Default | Description |
|---|---|---|---|
| `github-token` | string | ${GITHUB_TOKEN} | Github OAuth2 token to use when making Github API requests |
| `tag` | string |  | Cache tool version (tag name or "latest").  Should be at least v1.0.0.1.
For list of tags see https://github.com/haskell-works/cabal-cache/tags
 |
| `uri` | string |  | Cabal cache URI.  The location of the cabal-cache binary to download.  This is optional
 |

### perform-build

| Parameter | Type | Default | Description |
|---|---|---|---|
| `after-checkout` | steps |  | Optional steps to run after checkout |
| `build-steps` | steps |  | Steps to perform |
| `private-hackage-domain` | string |  | FQDN of private hackage repo. |
| `private-hackage-keys` | string |  | Root keys for private hackage repo. |
| `private-hackage-password` | string |  | Password on private hackage repo. |
| `private-hackage-user` | string |  | Username on private hackage repo. |
| `use-private-hackage` | boolean |  | Boolean for whether or not to use a private hackage repo. |
| `workspace-dir` | string |  | Result workspace directory name |
| `write-result-workspace` | boolean |  | Boolean for whether or not to persist results to a workspace. |

### restore-binary-cache

Capturing build environment (for caching)

| Parameter | Type | Default | Description |
|---|---|---|---|
| `binary-cache-opts` | string |  | AWS log level |
| `binary-cache-region` | string |  | Binary cache region.  This is one of the AWS regions. |
| `binary-cache-threads` | string |  | Number of threads for uploaded and downloading binary cache. |
| `binary-cache-uri` | string |  | Binary cache URI.  This may be an S3 URI. |
| `binary-cache-uri-suffix` | string |  | Binary cache URI suffix.  This defaults to empty.  When supplied the binary cache URI will be
extended to include the suffix via simple concatenation.
 |

### save-binary-cache

Capturing build environment (for caching)

| Parameter | Type | Default | Description |
|---|---|---|---|
| `binary-cache-opts` | string |  | AWS log level |
| `binary-cache-region` | string |  | Binary cache region.  This is one of the AWS regions. |
| `binary-cache-threads` | string |  | Number of threads for uploaded and downloading binary cache. |
| `binary-cache-uri` | string |  | Binary cache URI.  This may be an S3 URI. |
| `binary-cache-uri-suffix` | string |  | Binary cache URI suffix.  This defaults to empty.  When supplied the binary cache URI will be
extended to include the suffix via simple concatenation.
 |

### set-project-env

### set-project-params

| Parameter | Type | Default | Description |
|---|---|---|---|
| `build-documentation` | boolean |  | Build Haddock documentation that can be uploaded to Hackage |

## Jobs

### build

OBSOLETE. Use 'build-with-cci-cache'. Build with CircleCI cache.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `after-build` | steps |  | Optional steps to run after build but before running tests |
| `after-checkout` | steps |  | Optional steps to run after checkout |
| `after-test` | steps |  | Optional steps to run after executing unit tests |
| `before-build` | steps |  | Optional steps to run after cabal update but before build |
| `build-components` | string | all | Component names to build ("all" by default) |
| `build-components-separately` | boolean | false | Build specified components separately |
| `build-dependencies-first` | boolean | true | Build project first with "--dependencies-only".
This is useful for making sure that dependencies are cached even if the priject doesn't compile,
but can get in a way in some situations.  This parameter is only relevant to `build-with-cci-cache`
builds and is ignored by `build-with-binary-cache` builds.
 |
| `build-documentation` | boolean | false | Build Haddock documentation that can be uploaded to Hackage |
| `cabal-build-extra` | string |  | Extra CLI parameters to pass to the "cabal v2-build" command. |
| `cabal-test-extra` | string |  | Extra CLI parameters to pass to the "cabal v2-test" command. |
| `cabal-threads` | integer | 4 | Number of Cabal threads. |
| `cache-version` | string | ${CACHE_VERSION:-cache-01} | Cache version. Update this value when you want to start with new build caches. |
| `executor` | executor | ghc-8_4_4 | An executor that contains GHC and cabal-install (supporting v2-* commands family.)
"ghc-8_4_4" and "ghc-8_6_3" are provided, but custom executors can be used (see examples).
 |
| `fail-incoherent-builds` | boolean | true | Fail the build when immediate dependencies are incoherent |
| `private-hackage-domain` | string | ${PRIV_HACKAGE_DOMAIN} | FQDN of private hackage repo. |
| `private-hackage-keys` | string | ${PRIV_HACKAGE_KEYS} | Root keys for private hackage repo. |
| `private-hackage-password` | string | ${PRIV_HACKAGE_PASSWORD} | Password on private hackage repo. |
| `private-hackage-user` | string | ${PRIV_HACKAGE_LOGIN} | Username on private hackage repo. |
| `run-check` | boolean | true | Boolean for whether or not to check if the package has valid cabal file for distribution |
| `run-tests` | boolean | true | Boolean for whether or not to run unit tests |
| `test-no-output-timeout` | integer | 600 | No output timeout for tests |
| `use-private-hackage` | boolean | false | Boolean for whether or not to use a private hackage repo. |
| `workspace-dir` | string | build | Result workspace directory name |
| `write-result-workspace` | boolean | false | Boolean for whether or not to persist results to a workspace. |

### build-with-binary-cache

Build with binary caching using cabal-cache.
It requires at least 'binary-cache-uri' to be configured.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `after-build` | steps |  | Optional steps to run after build but before running tests |
| `after-checkout` | steps |  | Optional steps to run after checkout |
| `after-test` | steps |  | Optional steps to run after executing unit tests |
| `before-build` | steps |  | Optional steps to run after cabal update but before build |
| `binary-cache-opts` | string | ${BINARY_CACHE_OPTS} | AWS log level |
| `binary-cache-region` | string | ${BINARY_CACHE_REGION} | Binary cache region.  This is one of the AWS regions. |
| `binary-cache-threads` | string | ${BINARY_CACHE_THREADS} | Number of threads for uploaded and downloading binary cache. |
| `binary-cache-uri` | string | ${BINARY_CACHE_URI} | Binary cache URI.  This may be an S3 URI. |
| `binary-cache-uri-suffix` | string | ${BINARY_CACHE_SUFFIX} | Binary cache URI suffix.  This defaults to empty.  When supplied the binary cache URI will be
extended to include the suffix via simple concatenation.
 |
| `build-components` | string | all | Component names to build ("all" by default) |
| `build-components-separately` | boolean | false | Build specified components separately |
| `build-dependencies-first` | boolean | true | Build project first with "--dependencies-only".
This is useful for making sure that dependencies are cached even if the priject doesn't compile,
but can get in a way in some situations.  This parameter is only relevant to `build-with-cci-cache`
builds and is ignored by `build-with-binary-cache` builds.
 |
| `build-documentation` | boolean | false | Build Haddock documentation that can be uploaded to Hackage |
| `cabal-build-extra` | string |  | Extra CLI parameters to pass to the "cabal v2-build" command. |
| `cabal-cache-tag` | string | latest | Github tag of the 'cabal-cache' tool to use for binary caching. |
| `cabal-cache-uri` | string | ${CABAL_CACHE_URI} | Cabal cache URI.  The location of the cabal-cache binary to download. |
| `cabal-test-extra` | string |  | Extra CLI parameters to pass to the "cabal v2-test" command. |
| `cabal-threads` | integer | 4 | Number of Cabal threads. |
| `cache-version` | string | ${CACHE_VERSION:-cache-01} | Cache version. Update this value when you want to start with new build caches. |
| `executor` | executor | ghc-8_4_4 | An executor that contains GHC and cabal-install (supporting v2-* commands family.)
"ghc-8_4_4" and "ghc-8_6_3" are provided, but custom executors can be used (see examples).
 |
| `fail-incoherent-builds` | boolean | true | Fail the build when immediate dependencies are incoherent |
| `github-token` | string | ${GITHUB_TOKEN} | Github OAuth2 token to use when making Github API requests |
| `private-hackage-domain` | string | ${PRIV_HACKAGE_DOMAIN} | FQDN of private hackage repo. |
| `private-hackage-keys` | string | ${PRIV_HACKAGE_KEYS} | Root keys for private hackage repo. |
| `private-hackage-password` | string | ${PRIV_HACKAGE_PASSWORD} | Password on private hackage repo. |
| `private-hackage-user` | string | ${PRIV_HACKAGE_LOGIN} | Username on private hackage repo. |
| `run-check` | boolean | true | Boolean for whether or not to check if the package has valid cabal file for distribution |
| `run-tests` | boolean | true | Boolean for whether or not to run unit tests |
| `test-no-output-timeout` | integer | 600 | No output timeout for tests |
| `use-private-hackage` | boolean | false | Boolean for whether or not to use a private hackage repo. |
| `workspace-dir` | string | build | Result workspace directory name |
| `write-result-workspace` | boolean | false | Boolean for whether or not to persist results to a workspace. |

### build-with-cci-cache

Build with CircleCI cache.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `after-build` | steps |  | Optional steps to run after build but before running tests |
| `after-checkout` | steps |  | Optional steps to run after checkout |
| `after-test` | steps |  | Optional steps to run after executing unit tests |
| `before-build` | steps |  | Optional steps to run after cabal update but before build |
| `build-components` | string | all | Component names to build ("all" by default) |
| `build-components-separately` | boolean | false | Build specified components separately |
| `build-dependencies-first` | boolean | true | Build project first with "--dependencies-only".
This is useful for making sure that dependencies are cached even if the priject doesn't compile,
but can get in a way in some situations.  This parameter is only relevant to `build-with-cci-cache`
builds and is ignored by `build-with-binary-cache` builds.
 |
| `build-documentation` | boolean | false | Build Haddock documentation that can be uploaded to Hackage |
| `cabal-build-extra` | string |  | Extra CLI parameters to pass to the "cabal v2-build" command. |
| `cabal-test-extra` | string |  | Extra CLI parameters to pass to the "cabal v2-test" command. |
| `cabal-threads` | integer | 4 | Number of Cabal threads. |
| `cache-version` | string | ${CACHE_VERSION:-cache-01} | Cache version. Update this value when you want to start with new build caches. |
| `executor` | executor | ghc-8_4_4 | An executor that contains GHC and cabal-install (supporting v2-* commands family.)
"ghc-8_4_4" and "ghc-8_6_3" are provided, but custom executors can be used (see examples).
 |
| `fail-incoherent-builds` | boolean | true | Fail the build when immediate dependencies are incoherent |
| `private-hackage-domain` | string | ${PRIV_HACKAGE_DOMAIN} | FQDN of private hackage repo. |
| `private-hackage-keys` | string | ${PRIV_HACKAGE_KEYS} | Root keys for private hackage repo. |
| `private-hackage-password` | string | ${PRIV_HACKAGE_PASSWORD} | Password on private hackage repo. |
| `private-hackage-user` | string | ${PRIV_HACKAGE_LOGIN} | Username on private hackage repo. |
| `run-check` | boolean | true | Boolean for whether or not to check if the package has valid cabal file for distribution |
| `run-tests` | boolean | true | Boolean for whether or not to run unit tests |
| `test-no-output-timeout` | integer | 600 | No output timeout for tests |
| `use-private-hackage` | boolean | false | Boolean for whether or not to use a private hackage repo. |
| `workspace-dir` | string | build | Result workspace directory name |
| `write-result-workspace` | boolean | false | Boolean for whether or not to persist results to a workspace. |

## Executors

### ghc-7_10_3

### ghc-8_0_2

### ghc-8_2_2

### ghc-8_4_3

### ghc-8_4_4

### ghc-8_6_3

### ghc-8_6_4

### ghc-8_6_5

### ghc-8_8_1

### ghc-8_8_2

### ghc-8_8_3

### ghc-8_10_1

### ghc-8_10_2

### i386-ghc-7_10_3

### i386-ghc-8_0_2

### i386-ghc-8_2_2

### i386-ghc-8_4_3

### i386-ghc-8_4_4

### i386-ghc-8_6_3

### i386-ghc-8_6_4

### i386-ghc-8_6_5

### i386-ghc-8_8_1

### i386-ghc-8_8_2

### i386-ghc-8_8_3

### i386-ghc-8_10_1

### i386-ghc-8_10_2

### ubuntu-16_04-ghc-7_10_3

### ubuntu-16_04-ghc-8_0_2

### ubuntu-16_04-ghc-8_2_2

### ubuntu-16_04-ghc-8_4_3

### ubuntu-16_04-ghc-8_4_4

### ubuntu-16_04-ghc-8_6_3

### ubuntu-16_04-ghc-8_6_4

### ubuntu-16_04-ghc-8_6_5

### ubuntu-16_04-ghc-8_8_1

### ubuntu-16_04-ghc-8_8_2

### ubuntu-16_04-ghc-8_8_3

### ubuntu-16_04-ghc-8_10_1

### ubuntu-16_04-ghc-8_10_2

## Examples

### build-application

A typical workflow for building Haskell applications.
It uses the default executor (GHC 8.4.4) to build an app.


```yaml
orbs:
  haskell: haskell-works/haskell-build@1.6.6
version: 2.1
workflows:
  build-my-application:
    jobs:
      - haskell/build
```

### build-library

Building a library often requires building and testing it with multiple versions of GHC.
It also does not require producing binaries, so in this example we disable writing a workspace.


```yaml
orbs:
  haskell: haskell-works/haskell-build@1.6.6
version: 2.1
workflows:
  build-my-library:
    jobs:
      - haskell/build:
          executor: haskell/ghc-8_4_4
          name: GHC 8.4.4
      - haskell/build:
          executor: haskell/ghc-8_6_3
          name: GHC 8.6.3
```

### lifecycle-hooks

Use custom lifecycle hooks to add project-specific steps to a build process


```yaml
orbs:
  haskell: haskell-works/haskell-build@1.6.6
version: 2.1
workflows:
  build-my-application:
    jobs:
      - haskell/build:
          after-build:
            - run: echo "I run after build"
          after-test:
            - run: echo "I run after tests"
          before-build:
            - run: echo "I run before build"
```