Advanced Features

Dive into features for specialized use cases


This entire section is devoted to taking you through all the available configuration options for the packages in your build with the cabal.project file.

A cabal.project file allows you to select sets of packages in your build (both local and external packages) and apply configuration to them. Note that most flags of etlas build will have a corresponding entry in the cabal.project, but a cabal.project gives you much more flexibility.


Note that cabal.project.local and cabal.project.freeze follow the same specification, but they are meant for different purposes.

  • cabal.project.local is not meant to be checked into source control and is meant for local, ad-hoc changes to the build.
  • cabal.project.freeze is meant to be checked in if the project is an end-user executable and you want to keep the dependency resolution stable across platforms.

Field Types

The field types defined in the Cabal File section apply in this section as well. Additional field types are defined below.


A component name represents the name of a component like the name of an executable component for example.


A component type can take one of the following values:

  • lib
  • exe
  • test
  • bench


An Eta version is of the form [version]b[nonnegative-integer].


  • 0.8.6b4


A filepath glob is just like a filepath but it accepts * in the path to allow you to match multiple filepaths at once.


  • ./*.cabal
  • ./hello.cabal
  • hello.cabal


A flag specifier is either of the form +[flagname] or -[flagname] where + means to enable the flag and - means to disable the flag.


  • +developer
  • -slow


An index timestamp can either have the value HEAD or an ISO 8601 Date/Time Format.


  • HEAD
  • 2018-04-28T11:00:19Z


An integer is can be any whole number that is either positive or negative.


  • -1
  • 0
  • 1


An nonnegative integer is any whole number, including 0.


  • 0
  • 123


A num cpus can be a positive-integer or have the value $ncpus. The meaning of $ncpus is the number of processor cores on the system.


An optimization can take one of the following values:

  • 0
  • 1
  • 2


A package database can be one of the following:

  • global - Use the global package database (located in system directory)
  • user - Use the user package database (located in HOME folder)
  • clear - Reset the package database so far
  • [directory] - Path to the package database


A path template that can additionally use the specialized keywords defined in the table below in the path.

Template Variable Description
$prefix The root of all the Etlas-related data
$libname The name of the library
$bindir Where binaries are stored
$libdir Where libraries are installed
$datadir Where data files are installed
$docdir Where documentation is installed
$htmldir Where the html documentation is installed
$pkg Name of package
$version Version of package
$pkgid Name and version of package, e.g. binary-1.0
$compiler Name of compiler
$os Current operating system
$arch Current architecture
$abitag Tag that represents Application Binary Interface (ABI)
$abi Hash that represents Application Binary Interface (ABI)


An positive integer is any whole number, not including 0.


  • 1
  • 123


A scoped package can be of the form [package-name] or [package-name]:[package-name]. It can also take the values all or none.


  • bytestring
  • all
  • binary:bytestring
  • none


Scoped packages can be none, all, or strict-comma-list[scoped-package].


  • all
  • none
  • bytestring
  • bytestring,binary:bytestring


A transport type should be one of the following:

  • curl
  • wget
  • powershell
  • plain-http


A user constraint is of the form [package-name] [version-range] or [package-name] list[flag-specifier].


  • bytestring ==
  • bytestring +fast -developer


A verbosity is a number that can be one of the following values:

  • 0
  • 1
  • 2
  • 3

Local Packages

The following top-level options specify what the local packages of a project are:

Field Field Type Description
packages list[filepath-glob] List of package paths that should be included in the build.

Default: ./*.cabal
optional-packages list[filepath-glob] Like packages but does not require the paths to exist.

Default: ./*/*.cabal
extra-packages comma-list[dependency-constraint] Additional named packages to install to the Etlas Store



packages: . ./app
optional-packages: ./app/custom-fork
extra-packages: bytestring > 1.0.0

Global Configuration

The following top-level configuration options are not specific to any package:

Field Field Type Description
verbose verbosity Controls the verbosity of etlas commands, higher is more verbose.

Default: 1
jobs num-cpus Run the given number of jobs simultaneously when building.

Default: 1
keep-going boolean When true, continue to build other unaffected packages, after a build failure.

Default: False
builddir directory Specifies the directory where build artifacts should be stored.

Default: dist
project-file filepath Specifies the path to the project file which is used for the rest of the top-level configuration.

Default: cabal.project
select-eta eta-version Use an Etlas-managed version of Eta.
auto-update boolean Whether to update the package indices automatically.

Default: True
send-metrics boolean Whether to send metrics to help aid the future development of Eta.

Default: False
http-transport transport-type Transport to be used when making http(s) requests.

Default: curl
ignore-expiry boolean Ignore expiry dates on metadata from Hackage.

Default: False
remote-repo-cache directory Location where source tarballs downloaded from remote repositories are stored.

Default: ~/.etlas/packages
logs-dir directory Location where build logs are stored.

Default: ~/.etlas/logs
patches-dir directory Directory where patches are stored.

Default: ~/.etlas/patches
binaries-dir directory Directory where downloaded binary executables and packages are stored.

Default: ~/.etlas/binaries
build-summary path-template Location where the build summary is stored.

Default: ~/.etlas/logs/build.log

Solver Configuration

The following settings control the behavior of the dependency solver. All the fields are commas seperated

Field Field Type Description
constraints comma-list[user-constraint] Add version or flag constraints for dependencies.
preferences comma-list[dependency-constraint] Dependency constraints are taken into account, but loosely followed.
allow-newer scoped-packages Ignore upper bounds for the list of scoped packages.

Default: none
allow-older scoped-packages Ignore lower bounds for the list of scoped packages.

Default: none
index-state index-timestamp Set the source package index state to the given value.

Default: HEAD
max-backjumps integer Maximum number of backtracking steps allowed while solving.

-1 to allow unlimited backtracking

0 to disable backtracking completely

Default: 2000
reorder-goals boolean Enable the solver to reorder goals according to certain heuristics.

Default: False
count-conflicts boolean Speed up solving by preferring goals that are involved in a lot of conflicts.

Default: True
strong-flags boolean Do not defer flag choices.

Default: False
allow-boot-library-installs boolean Allow base, ghc-prim, integer-simple, integer-gmp, and template-haskell to be installed or upgraded.

Default: False

Package Configuration

The following options can affect individual packages or sets of packages.


If package options are specified at the top-level, they apply to all local packages.


optimization: 2


If they are applied in an all-packages stanza, it applies to both local and external packages.


  optimization: 2


If they are applied in a package stanza, they will apply to the package listed after the package keyword. Both local and external package names may be specified.


package bytestring
  optimization: 2

Option Listing

Field Field Type Description
flags list[flag-specifier] Configure flag assignments for the package
optimization optimization Build with optimization at the level specified.

Default: 1
tests boolean Enable test suites.

Default: False
benchmarks boolean Enable benchmarks.

Default: False
run-tests boolean Run the package test suite upon installation and fail the build if it doesn't pass.

Default: False
verify boolean Verifies the whether the output JAR files are valid
debug-info boolean Generate extra information in the compiled binary that supports debugging.

Default: False

Documentation Configuration

Field Field Type Description
documentation boolean Enables documentation build.

Default: False
doc-index-file path-template Path to central index of API documentation
docs-html boolean Build HTML documentation.

Default: True.
docs-html-location path-template Specify template for the location of HTML documentation for prerequisite packages
docs-executables boolean Generate documentation for all executables.

Default: False
docs-tests boolean Generate documentation for all tests.

Default: False
docs-benchmarks boolean Generate documentation for all benchmarks.

Default: False
docs-all boolean Generate documentation for all components.

Default: False
docs-internal boolean Generate documentation for hidden modules and symbols.

Default: False
docs-css filepath Path to CSS file that styles the generated documentation
docs-contents-location url URL to be used as the location for the contents page
docs-keep-temp-files boolean Keep temporary files

Default: False