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

# haskell-works/haskell-build-2

Builds a Haskell application using cabal v2-*.

## Commands

### override-ghc

### describe-build

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

### install-cabal-cache

| Parameter | Type | Default | Description |
|---|---|---|---|
| `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
 |

### restore-binary-cache

Capturing build environment (for caching)

| Parameter | Type | Default | Description |
|---|---|---|---|
| `binary-cache-uri` | string |  | Binary cache URI.  This may be an S3 URI. |
| `binary-cache-region` | string |  | 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-opts` | string | ${BINARY_CACHE_OPTS} | AWS log level |

### save-binary-cache

Capturing build environment (for caching)

| Parameter | Type | Default | Description |
|---|---|---|---|
| `binary-cache-uri` | string | ${BINARY_CACHE_URI} | Binary cache URI.  This may be an S3 URI. |
| `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-opts` | string | ${BINARY_CACHE_OPTS} | AWS log level |

### 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. |

### set-project-env

### copy-bin

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

### check-immediate-dependencies-coherence

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

### add-private-hackage-repo

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

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

## Jobs

### build

| Parameter | Type | Default | Description |
|---|---|---|---|
| `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).
 |
| `cache-version` | string | ${CACHE_VERSION:-cache-01} | Cache version. Update this value when you want to start with new build caches. |
| `cabal-threads` | integer | 4 | Number of Cabal threads. |
| `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. |
| `fail-incoherent-builds` | boolean | true | Fail the build when immediate dependencies are incoherent |
| `run-tests` | boolean | true | Boolean for whether or not to run unit tests |
| `run-check` | boolean | true | Boolean for whether or not to check if the package has valid cabal file for distribution |
| `write-result-workspace` | boolean | false | Boolean for whether or not to persist results to a workspace. |
| `workspace-dir` | string | build | Result workspace directory name |
| `after-checkout` | steps |  | Optional steps to run after checkout |
| `before-build` | steps |  | Optional steps to run after cabal update but before build |
| `after-build` | steps |  | Optional steps to run after build but before running tests |
| `after-test` | steps |  | Optional steps to run after executing unit tests |
| `cabal-cache-tag` | string | latest | Cabal cache tag |
| `binary-cache-uri` | string | ${BINARY_CACHE_URI} | Binary cache URI.  This may be an S3 URI. |
| `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-opts` | string | ${BINARY_CACHE_OPTS} | AWS log level |
| `use-private-hackage` | boolean | false | Boolean for whether or not to use a private hackage repo. |
| `private-hackage-user` | string | ${PRIV_HACKAGE_LOGIN} | Username on private hackage repo. |
| `private-hackage-password` | string | ${PRIV_HACKAGE_PASSWORD} | Password on private hackage repo. |
| `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. |

## Executors

### ghc-7_10_3

### ghc-8_0_2

### ghc-8_2_2

### ghc-8_4_4

### ghc-8_4_3

### ghc-8_6_3

### ghc-8_6_4

### ghc-8_6_5

### ghc-844

### ghc-863

## Examples

### build-application

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


```yaml
version: 2.1
orbs:
  haskell: haskell-works/haskell-build-2@1.6.8
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
version: 2.1
orbs:
  haskell: haskell-works/haskell-build-2@1.6.8
workflows:
  build-my-library:
    jobs:
      - haskell/build:
          name: GHC 8.4.4
          executor: haskell/ghc-8_4_4
      - haskell/build:
          name: GHC 8.6.3
          executor: haskell/ghc-8_6_3
```

### life-cycle-hooks

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


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