A query against a package's Cabal configuration. Use runQuery to execute it.

The version of GHC the project is configured to use for compilation.

All local packages currently active in a project's build plan.

Cabal flags to set when configuring and building this package.

A Unit is essentially a "build target". It is used to refer to a set of components (exes, libs, tests etc.) which are managed by a certain instance of the Cabal build-system[1]. We may get information on the components in a unit by retriving the corresponding UnitInfo.

[1]: No I'm not talking about the cabal-install build-tool, I'm talking about the Cabal build-system. Note the distinction. Both cabal-install and Stack use the Cabal build-system (aka lib:Cabal) underneath.

Note that a Unit value is only valid within the QueryEnv context it was created in, this is however this is not enforced by the API. Furthermore if the user changes the underlying project configuration while your application is running even a properly scoped Unit could become invalid because the component it belongs to was removed from the cabal file.

This returns the component a Unit corresponds to. This information is only available if the correspondence happens to be unique and known before querying setup-config for the respective project type. Currently this only applies to pt=V2.

This is intended to be used as an optimization, to allow reducing the number of helper invocations for clients that don't need to know the entire project structure.

The information extracted from a 'Unit'\'s on-disk configuration cache.

Get the UnitInfo for a given Unit. To get a Unit see projectUnits.

Get information on all units in a project.

Environment for running a Query. The constructor is not exposed in the API to allow extending it with more fields without breaking user code.

To create a QueryEnv use the mkQueryEnv smart constructor instead. Some field accessors are exported and may be used to override the defaults filled in by mkQueryEnv. See below.

Note that this environment contains an IORef used as a cache. If you want to take advantage of this you should not simply discard the value returned by the smart constructor after one use.

mkQueryEnv projdir distdir. Smart constructor for QueryEnv. Sets fields qeProjLoc and qeDistDir to projdir and distdir respectively and provides sensible defaults for the other fields.

Field accessor for QueryEnv. Function used to to start processes and capture output. Useful if you need to, for example, redirect standard error output of programs started by cabal-helper.

Field accessor for QueryEnv. Function used to to start processes without capturing output. See also qeReadProcess.

Field accessor for QueryEnv. Paths to various programs we use.

Field accessor for QueryEnv. Defines path to the project directory, i.e. a directory containing a cabal.project file

Field accessor for QueryEnv. Defines path to the dist/ or dist-newstyle/ directory, aka. builddir in Cabal terminology.

The kind of project being managed by a QueryEnv (pun intended). Used as a phantom-type variable throughout to make the project type being passed into various functions correspond to the correct implementation.

The kind of a cabal project.

Location of a project context. This is usually just the path project's top-level source code directory together with an optional project-type specific config file path.

To find any recognized default project contexts in a given directory use findProjects.

Build tools usually allow the user to specify the location of their project config files manually, so we also support passing this path here with the *File constructors.

Correspondence between Project and Package Source Directories

Note that the project's source directory does not necessarily correspond to the directory containing the project config file, though in some cases it does.

For example cabal v2-build allows the cabal.project file to be positively anywhere in the filesystem when specified via the --cabal-project command-line flag, corresponding to the ProjLocV2File constructor here. This config file can then refer to package directories with absolute paths in the packages: declaration.

Hence it isn't actually possible to find one directory which contains the whole project's source code but rather we have to consider each package's source directory individually, see pSourceDir

A build directory for a certain project type. The pt type variable must be compatible with the ProjLoc used. This is enforced by the type system so you can't get this wrong.

A "singleton" datatype for ProjType which allows us to establish a correspondence between a runtime representation of ProjType to the compile-time value at the type level.

If you just want to know the runtime ProjType use demoteSProjType to convert to that.

This is a singleton, like SProjType, but restricted to just the Cabal project types. We use this to restrict some functions which don't make sense for Stack to just the Cabal project types.

General purpose existential wrapper. Useful for hiding a phantom type argument.

Say you have:

{-# LANGUAGE DataKinds, GADTS #-}
data K = A | B | ...
data Q k where
  QA :: ... -> Q 'A
  QB :: ... -> Q 'B

and you want a list of Q. You can use Ex to hide the phantom type argument and recover it later by matching on the GADT constructors:

qa :: Q A
qa = QA

qb :: Q B
qb = QB

mylist :: [Ex Q]
mylist = [Ex qa, Ex qb]

Configurable paths to various programs we use.

By default all programs use their unqualified names, i.e. they will be searched for on PATH.

Get the path to the sandbox package-db in a project

Make sure the appropriate helper executable for the given project is installed and ready to run queries.

The idea is you can run this at a convinient time instead of having the helper compilation happen during a time-sensitive user interaction. This will however happen automatically as needed if you don't run it first.

Create cabal_macros.h, Paths_<pkg>.hs and other generated files in the usual place. See initialBuildSteps.

This is usually only needed on the first load of a unit or after the cabal file changes.