Advanced Features
Dive into features for specialized use cases
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.
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:
An Eta version is of the form [version]b[nonnegative-integer].
Examples
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.
Examples
A flag specifier is either of the form +[flagname] or -[flagname] where + means to enable the flag and - means to disable the flag.
Examples
An index timestamp can either have the value HEAD or an ISO 8601 Date/Time Format.
Examples
An integer is can be any whole number that is either positive or negative.
Examples
An nonnegative integer is any whole number, including 0.
Examples
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:
A package database can be one of the following:
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.
Examples
A scoped package can be of the form [package-name] or [package-name]:[package-name]. It can also take the values all or none.
Examples
Scoped packages can be none, all, or strict-comma-list[scoped-package].
Examples
A transport type should be one of the following:
A user constraint is of the form [package-name] [version-range] or [package-name] list[flag-specifier].
Examples
A verbosity is a number that can be one of the following values:
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. |
| optional-packages | list[filepath-glob] | Like packages but does not require the paths to exist. |
| extra-packages | comma-list[dependency-constraint] | Additional named packages to install to the Etlas Store |
cabal.project
packages: . ./app
optional-packages: ./app/custom-fork
extra-packages: bytestring > 1.0.0
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. |
| jobs | num-cpus | Run the given number of jobs simultaneously when building. |
| keep-going | boolean | When true, continue to build other unaffected packages, after a build failure. |
| builddir | directory | Specifies the directory where build artifacts should be stored. |
| project-file | filepath | Specifies the path to the project file which is used for the rest of the top-level configuration. |
| select-eta | eta-version | Use an Etlas-managed version of Eta. |
| auto-update | boolean | Whether to update the package indices automatically. |
| send-metrics | boolean | Whether to send metrics to help aid the future development of Eta. |
| http-transport | transport-type | Transport to be used when making http(s) requests. |
| ignore-expiry | boolean | Ignore expiry dates on metadata from Hackage. |
| remote-repo-cache | directory | Location where source tarballs downloaded from remote repositories are stored. |
| logs-dir | directory | Location where build logs are stored. |
| patches-dir | directory | Directory where patches are stored. |
| binaries-dir | directory | Directory where downloaded binary executables and packages are stored. |
| build-summary | path-template | Location where the build summary is stored. |
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. |
| allow-older | scoped-packages | Ignore lower bounds for the list of scoped packages. |
| index-state | index-timestamp | Set the source package index state to the given value. |
| max-backjumps | integer | Maximum number of backtracking steps allowed while solving. |
| reorder-goals | boolean | Enable the solver to reorder goals according to certain heuristics. |
| count-conflicts | boolean | Speed up solving by preferring goals that are involved in a lot of conflicts. |
| strong-flags | boolean | Do not defer flag choices. |
| allow-boot-library-installs | boolean | Allow base, ghc-prim, integer-simple, integer-gmp, and template-haskell to be installed or upgraded. |
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.
Example
optimization: 2
If they are applied in an all-packages stanza, it applies to both local and external packages.
Example
all-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.
Example
package bytestring
optimization: 2
| Field | Field Type | Description |
| flags | list[flag-specifier] | Configure flag assignments for the package |
| optimization | optimization | Build with optimization at the level specified. |
| tests | boolean | Enable test suites. |
| benchmarks | boolean | Enable benchmarks. |
| run-tests | boolean | Run the package test suite upon installation and fail the build if it doesn't pass. |
| verify | boolean | Verifies the whether the output JAR files are valid |
| debug-info | boolean | Generate extra information in the compiled binary that supports debugging. |
| Field | Field Type | Description |
| documentation | boolean | Enables documentation build. |
| doc-index-file | path-template | Path to central index of API documentation |
| docs-html | boolean | Build HTML documentation. |
| docs-html-location | path-template | Specify template for the location of HTML documentation for prerequisite packages |
| docs-executables | boolean | Generate documentation for all executables. |
| docs-tests | boolean | Generate documentation for all tests. |
| docs-benchmarks | boolean | Generate documentation for all benchmarks. |
| docs-all | boolean | Generate documentation for all components. |
| docs-internal | boolean | Generate documentation for hidden modules and symbols. |
| 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 |