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].
A filepath glob is just like a filepath but it accepts * in the path to allow you to match multiple filepaths at once.
A flag specifier is either of the form +[flagname] or -[flagname] where + means to enable the flag and - means to disable the flag.
An index timestamp can either have the value HEAD or an ISO 8601 Date/Time Format.
An integer is can be any whole number that is either positive or negative.
An nonnegative integer is any whole number, including 0.
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.
|$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|
|$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.
A scoped package can be of the form [package-name] or [package-name]:[package-name]. It can also take the values all or none.
Scoped packages can be none, all, or strict-comma-list[scoped-package].
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].
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:
|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|
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:
|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
|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. |
-1 to allow unlimited backtracking
0 to disable backtracking completely
|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.
If they are applied in an all-packages stanza, it applies to both local and external packages.
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.
package bytestring optimization: 2
|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. |
|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 |