<commit_before># YAML Configuration

This page is intended to fully document all configuration options available in the stack.yaml file. Note that this page is likely to be both *incomplete* and sometimes *inaccurate*. If you see such cases, please update the page, and if you're not sure how, open an issue labeled "question".

The stack.yaml configuration options break down into [project specific](#project-config) options in:

- `<project dir>/stack.yaml`

and [non-project specific](#non-project-config) options in:

- `/etc/stack/config.yaml` -- for system global non-project default options
-  `~/.stack/config.yaml` -- for user non-project default options
- The project file itself may also contain non-project specific options

*Note:* When stack is invoked outside a stack project it will source project specific options from `~/.stack/global/stack.yaml`.  Options in this file will be ignored for a project with its own `<project dir>/stack.yaml`.

## Project config

Project specific options are only valid in the `stack.yaml` file local to a project, not in the user or global config files.

### packages

The `packages` section lists all local (project) packages. The term  _local
package_ should be differentiated from a _dependency package_. A local package
is something that you are developing as part of the project. Whereas a
dependency package is an external package that your project depends on.

In its simplest usage, it will be a list of directories or HTTP(S) URLs to a
tarball or a zip. For example:

```yaml
packages:
  - .
  - dir1/dir2
  - https://example.com/foo/bar/baz-0.0.2.tar.gz
```

Each package directory or location specified must have a valid cabal file
present. Note that the subdirectories of the directory are not searched for
cabal files. Subdirectories will have to be specified as independent items in
the list of packages.

When the `packages` field is not present, it defaults to looking for a package
in the project's root directory:

```yaml
packages:
  - .
```
#### Complex package locations (`location`)

More complex package locations can be specified in a key-value format with
`location` as a mandatory key.  In addition to `location` some optional
key-value pairs can be specified to include specific subdirectories or to
specify package attributes as descibed later in this section.

In its simplest form a `location` key can have a single value in the same way
as described above for single value items. Alternativel it can have key-value
pairs as subfields to describe a git or mercurial repository location. For
example:

```yaml
packages:
- location: .
- location: dir1/dir2
- location: https://example.com/foo/bar/baz-0.0.2.tar.gz
- location: http://github.com/yesodweb/wai/archive/2f8a8e1b771829f4a8a77c0111352ce45a14c30f.zip
- location:
    git: <EMAIL>:commercialhaskell/stack.git
    commit: 6a86ee32e5b869a877151f74064572225e1a0398
- location:
    hg: https://example.com/hg/repo
    commit: da39a3ee5e6b4b0d3255bfef95601890afd80709
```

Note: it is highly recommended that you only use SHA1 values for a Git or
Mercurial commit. Other values may work, but they are not officially supported,
and may result in unexpected behavior (namely, stack will not automatically
pull to update to new versions).

A `location` key can be accompanied by a `subdirs` key to look for cabal files
in a list of subdirectories as well in addition to the top level directory.

This could be useful for mega-repos like
[wai](https://github.com/yesodweb/wai/) or
[digestive-functors](https://github.com/jaspervdj/digestive-functors).

The `subdirs` key can have multiple nested series items specifying a list of
subdirectories.  For example:
```yaml
packages:
- location: .
  subdirs:
  - subdir1
  - subdir2
- location:
    git: <EMAIL>:yesodweb/wai
    commit: <PASSWORD>
  subdirs:
  - auto-update
  - wai
- location: http://github.com/yesodweb/wai/archive/2f8a8e1b771829f4a8a77c0111352ce45a14c30f.zip
  subdirs:
  - auto-update
  - wai
```

#### Local dependency packages (`extra-dep`)
A `location` key can be accompanied by an `extra-dep` key.  When the
`extra-dep` key is set to `true` it indicates that the package should be
treated in the same way as a dependency package and not as part of the project.
This means the following:
* A _dependency package_ is built only if a user package or its dependencies
  depend on it. Note that a regular _project package_ is built anyway even if
  no other package depends on it.
* Its test suites and benchmarks will not be run.
* It will not be directly loaded in ghci when `stack ghci` is run. This is
  important because if you specify huge dependencies as project packages then
  ghci will have a nightmare loading everything.

This is especially useful when you are tweaking upstream packages or want to
use latest versions of the upstream packages which are not yet on Hackage or
Stackage.

For example:
```yaml
packages:
- location: .
- location: vendor/binary
  extra-dep: true
- location:
    git: <EMAIL>:yesodweb/wai
    commit: <PASSWORD>
  subdirs:
  - auto-update
  - wai
  extra-dep: true
```

### extra-deps

This is a list of package identifiers for additional packages from upstream to
be included. This is usually used to augment an LTS Haskell or Stackage Nightly
snapshot with a package that is not present or is at an different version than you
wish to use.

```yaml
extra-deps:
- acme-missiles-0.3
```

Note that the `extra-dep` attribute in the `packages` section as described in
an earlier section is used for non-index local or remote packages while the
`extra-deps` section is for packages to be automatically pulled from an index
like Hackage.

### resolver

Specifies how dependencies are resolved. There are currently four resolver types:

* LTS Haskell snapshots, e.g. `resolver: lts-2.14`
* Stackage Nightly snapshot, e.g. `resolver: nightly-2015-06-16`
* No snapshot, just use packages shipped with the compiler
    * For GHC this looks like `resolver: ghc-7.10.2`
    * For GHCJS this looks like `resolver: ghcjs-0.1.0_ghc-7.10.2`.
* [Custom snapshot](https://github.com/commercialhaskell/stack/wiki/Custom-Snapshot)

Each of these resolvers will also determine what constraints are placed on the compiler version. See the [compiler-check](#compiler-check) option for some additional control over compiler version.

### flags

Flags can be set for each package separately, e.g.

```yaml
flags:
  package-name:
    flag-name: true
```

Flags will only affect packages in your `packages` and `extra-deps` settings.
Packages that come from the snapshot global database are not affected.

### image

The image settings are used for the creation of container images using `stack
image container`, e.g.

```yaml
image:
  containers:
    - base: "fpco/stack-build"
      add:
        static: /data/static
```

`base` is the docker image that will be used to built upon. The `add` lines
allow you to add additional directories to your image. You can specify the name
of the image using `name` (otherwise it defaults to the same as your project).
You can also specify `entrypoints`. By default all your executables are placed
in `/usr/local/bin`, but you can specify a list using `executables` to only add
some.

### user-message

A user-message is inserted by `stack init` when it omits packages or adds
external dependencies. For example:

```yaml
user-message: ! 'Warning: Some packages were found to be incompatible with the resolver
  and have been left commented out in the packages section.

  Warning: Specified resolver could not satisfy all dependencies. Some external packages
  have been added as dependencies.

  You can suppress this message by removing it from stack.yaml

'
```

This messages is displayed every time the config is loaded by stack and serves
as a reminder for the user to review the configuration and make any changes if
needed. The user can delete this message if the generated configuration is
acceptable.

## Non-project config

Non-project config options may go in the global config (`/etc/stack/config.yaml`) or the user config (`~/.stack/config.yaml`).

### docker

See [Docker integration](docker_integration.md#configuration).

### nix

(since 0.1.10.0)

See [Nix integration](nix_integration.md#configuration).

### connection-count

Integer indicating how many simultaneous downloads are allowed to happen

Default: `8`

### hide-th-loading

Strip out the "Loading ..." lines from GHC build output, produced when using Template Haskell

Default: `true`<commit_msg>Edit "Yaml Configuration" page in documention<commit_after># YAML Configuration

This page is intended to fully document all configuration options available in the stack.yaml file. Note that this page is likely to be both *incomplete* and sometimes *inaccurate*. If you see such cases, please update the page, and if you're not sure how, open an issue labeled "question".

The stack.yaml configuration options break down into [project-specific](#project-config) options in:

- `<project dir>/stack.yaml`

and [non-project-specific](#non-project-config) options in:

- `/etc/stack/config.yaml` -- for system global non-project default options
-  `~/.stack/config.yaml` -- for user non-project default options
- The project file itself may also contain non-project specific options

*Note:* When stack is invoked outside a stack project it will source project specific options from `~/.stack/global/stack.yaml`.  Options in this file will be ignored for a project with its own `<project dir>/stack.yaml`.

## Project-specific config

Project-specific options are only valid in the `stack.yaml` file local to a project, not in the user or global config files.

> Note: We define **project** to mean a directory that contains a `stack.yaml`
> file. We define **package** the same way that Cabal defines a package. (This
> means a single `.cabal` file---which may contain a library, a test suite, and
> multiple executables.) Note that a single **Stack project** may contain
> several **packages**---which might be located in a directory on your
> computer, on Hackage, in a remote Git or Mercurial repository, or even in a
> tarball somewhere on the internet.

In your project-specific options, you specify both **which of your packages**
to build and **which dependencies to use** when building these packages. Stack
treats _packages_ and _dependencies_ differently. For dependencies, Stack only
builds the library part, while for packages Stack builds the library, the
executables, and the test suite.

The below sections will show you how to tell Stack where to find your packages
and dependencies.

Note, using the options described below, it **is possible** to specify in your
`stack.yaml` multiple sources of the same package/dependency. For example, you
might specify a version of a project on your local machine, a Stackage snapshot
that contains the same package, as well as a version of the same package on
Hackage. For simplicity, **Stack will only use one version of each
package/dependency.** There are rules that dictate how Stack chooses which
version to use. Read [the section on
"shadowing"](http://docs.haskellstack.org/en/stable/architecture/#shadowing) to
learn more about these rules.

### packages

The `packages` section lists all local (project) packages. The term  _local
package_ should be differentiated from a _dependency package_. A local package
is something that you are developing as part of the project. Whereas a
dependency package is an external package that your project depends on.

In its simplest usage, it will be a list of directories or HTTP(S) URLs to a
tarball or a zip. For example:

```yaml
packages:
  - .
  - dir1/dir2
  - https://example.com/foo/bar/baz-0.0.2.tar.gz
```

Each package directory or location specified must have a valid cabal file
present. Note that the subdirectories of the directory are not searched for
cabal files. Subdirectories will have to be specified as independent items in
the list of packages.

When the `packages` field is not present, it defaults to looking for a package
in the project's root directory:

```yaml
packages:
  - .
```
#### Complex package locations (`location`)

More complex package locations can be specified in a key-value format with
`location` as a mandatory key.  In addition to `location` some optional
key-value pairs can be specified to include specific subdirectories or to
specify package attributes as descibed later in this section.

In its simplest form a `location` key can have a single value in the same way
as described above for single value items. Alternativel it can have key-value
pairs as subfields to describe a git or mercurial repository location. For
example:

```yaml
packages:
- location: .
- location: dir1/dir2
- location: https://example.com/foo/bar/baz-0.0.2.tar.gz
- location: http://github.com/yesodweb/wai/archive/2f8a8e1b771829f4a8a77c0111352ce45a14c30f.zip
- location:
    git: <EMAIL>:commercialhaskell/stack.git
    commit: <PASSWORD>572225e1a0398
- location:
    hg: https://example.com/hg/repo
    commit: da39a3ee5e6b4b0d3255bfef95601890afd80709
```

Note: it is highly recommended that you only use SHA1 values for a Git or
Mercurial commit. Other values may work, but they are not officially supported,
and may result in unexpected behavior (namely, stack will not automatically
pull to update to new versions).

A `location` key can be accompanied by a `subdirs` key to look for cabal files
in a list of subdirectories as well in addition to the top level directory.

This could be useful for mega-repos like
[wai](https://github.com/yesodweb/wai/) or
[digestive-functors](https://github.com/jaspervdj/digestive-functors).

The `subdirs` key can have multiple nested series items specifying a list of
subdirectories.  For example:
```yaml
packages:
- location: .
  subdirs:
  - subdir1
  - subdir2
- location:
    git: <EMAIL>:yesodweb/wai
    commit: 2f8a8e1b771829f4a8a77c0111352ce45a14c30f
  subdirs:
  - auto-update
  - wai
- location: http://github.com/yesodweb/wai/archive/2f8a8e1b771829f4a8a77c0111352ce45a14c30f.zip
  subdirs:
  - auto-update
  - wai
```

#### Local dependency packages (`extra-dep`)
A `location` key can be accompanied by an `extra-dep` key.  When the
`extra-dep` key is set to `true` it indicates that the package should be
treated in the same way as a dependency package and not as part of the project.
This means the following:
* A _dependency package_ is built only if a user package or its dependencies
  depend on it. Note that a regular _project package_ is built anyway even if
  no other package depends on it.
* Its test suites and benchmarks will not be run.
* It will not be directly loaded in ghci when `stack ghci` is run. This is
  important because if you specify huge dependencies as project packages then
  ghci will have a nightmare loading everything.

This is especially useful when you are tweaking upstream packages or want to
use latest versions of the upstream packages which are not yet on Hackage or
Stackage.

For example:
```yaml
packages:
- location: .
- location: vendor/binary
  extra-dep: true
- location:
    git: <EMAIL>:yesodweb/wai
    commit: <PASSWORD>
  subdirs:
  - auto-update
  - wai
  extra-dep: true
```

### extra-deps

This is a list of package identifiers for additional packages from upstream to
be included. This is usually used to augment an LTS Haskell or Stackage Nightly
snapshot with a package that is not present or is at an different version than you
wish to use.

```yaml
extra-deps:
- acme-missiles-0.3
```

Note that the `extra-dep` attribute in the `packages` section as described in
an earlier section is used for non-index local or remote packages while the
`extra-deps` section is for packages to be automatically pulled from an index
like Hackage.

### resolver

Specifies how dependencies are resolved. There are currently four resolver types:

* LTS Haskell snapshots, e.g. `resolver: lts-2.14`
* Stackage Nightly snapshot, e.g. `resolver: nightly-2015-06-16`
* No snapshot, just use packages shipped with the compiler
    * For GHC this looks like `resolver: ghc-7.10.2`
    * For GHCJS this looks like `resolver: ghcjs-0.1.0_ghc-7.10.2`.
* [Custom snapshot](https://github.com/commercialhaskell/stack/wiki/Custom-Snapshot)

Each of these resolvers will also determine what constraints are placed on the compiler version. See the [compiler-check](#compiler-check) option for some additional control over compiler version.

### flags

Flags can be set for each package separately, e.g.

```yaml
flags:
  package-name:
    flag-name: true
```

Flags will only affect packages in your `packages` and `extra-deps` settings.
Packages that come from the snapshot global database are not affected.

### image

The image settings are used for the creation of container images using `stack
image container`, e.g.

```yaml
image:
  containers:
    - base: "fpco/stack-build"
      add:
        static: /data/static
```

`base` is the docker image that will be used to built upon. The `add` lines
allow you to add additional directories to your image. You can specify the name
of the image using `name` (otherwise it defaults to the same as your project).
You can also specify `entrypoints`. By default all your executables are placed
in `/usr/local/bin`, but you can specify a list using `executables` to only add
some.

### user-message

A user-message is inserted by `stack init` when it omits packages or adds
external dependencies. For example:

```yaml
user-message: ! 'Warning: Some packages were found to be incompatible with the resolver
  and have been left commented out in the packages section.

  Warning: Specified resolver could not satisfy all dependencies. Some external packages
  have been added as dependencies.

  You can suppress this message by removing it from stack.yaml

'
```

This messages is displayed every time the config is loaded by stack and serves
as a reminder for the user to review the configuration and make any changes if
needed. The user can delete this message if the generated configuration is
acceptable.

## Non-project-specific config

Non-project config options may go in the global config (`/etc/stack/config.yaml`) or the user config (`~/.stack/config.yaml`).

### docker

See [Docker integration](docker_integration.md#configuration).

### nix

(since 0.1.10.0)

See [Nix integration](nix_integration.md#configuration).

### connection-count

Integer indicating how many simultaneous downloads are allowed to happen

Default: `8`

### hide-th-loading

Strip out the "Loading ..." lines from GHC build output, produced when using Template Haskell

Default: `true`
{'fraction_non_alphanumeric': 0.07461406518010291, 'fraction_numerical': 0.01667024013722127, 'mean_word_length': 4.165282392026578, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 24, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1748090', 'n_tokens_mistral': 5430, 'n_tokens_neox': 5143, 'n_words': 2509}