cabal-install-3.12.1.0: The command-line interface for Cabal and Hackage.

Safe Haskell | None
Language | Haskell2010

Distribution.Client.ProjectBuilding

Contents

- Dry run phase
  - Build status
- Build phase
  - Build outcomes

Synopsis

- rebuildTargetsDryRun :: DistDirLayout -> ElaboratedSharedConfig -> ElaboratedInstallPlan -> IO BuildStatusMap
- improveInstallPlanWithUpToDatePackages :: BuildStatusMap -> ElaboratedInstallPlan -> ElaboratedInstallPlan
- type BuildStatusMap = Map UnitId BuildStatus
- data BuildStatus
  - = BuildStatusPreExisting
  - | BuildStatusInstalled
  - | BuildStatusDownload
  - | BuildStatusUnpack FilePath
  - | BuildStatusRebuild FilePath BuildStatusRebuild
  - | BuildStatusUpToDate BuildResult
- data BuildStatusRebuild
  - = BuildStatusConfigure (MonitorChangedReason ())
  - | BuildStatusBuild (Maybe (Maybe InstalledPackageInfo)) BuildReason
- data BuildReason
  - = BuildReasonDepsRebuilt
  - | BuildReasonFilesChanged (MonitorChangedReason ())
  - | BuildReasonExtraTargets (Set ComponentName)
  - | BuildReasonEphemeralTargets
- data MonitorChangedReason a
  - = MonitoredFileChanged FilePath
  - | MonitoredValueChanged a
  - | MonitorFirstRun
  - | MonitorCorruptCache
- buildStatusToString :: BuildStatus -> String
- rebuildTargets :: Verbosity -> ProjectConfig -> DistDirLayout -> StoreDirLayout -> ElaboratedInstallPlan -> ElaboratedSharedConfig -> BuildStatusMap -> BuildTimeSettings -> IO BuildOutcomes
- type BuildOutcomes = Map UnitId BuildOutcome
- type BuildOutcome = Either BuildFailure BuildResult
- data BuildResult = BuildResult {
  - buildResultDocs :: DocsResult
  - buildResultTests :: TestsResult
  - buildResultLogFile :: Maybe FilePath
  }
- data BuildFailure = BuildFailure {
  - buildFailureLogFile :: Maybe FilePath
  - buildFailureReason :: BuildFailureReason
  }
- data BuildFailureReason
  - = DependentFailed PackageId
  - | GracefulFailure String
  - | DownloadFailed SomeException
  - | UnpackFailed SomeException
  - | ConfigureFailed SomeException
  - | BuildFailed SomeException
  - | ReplFailed SomeException
  - | HaddocksFailed SomeException
  - | TestsFailed SomeException
  - | BenchFailed SomeException
  - | InstallFailed SomeException

# Dry run phase

What bits of the plan will we execute? The dry run does not change anything but tells us what will need to be built.

rebuildTargetsDryRun :: DistDirLayout -> ElaboratedSharedConfig -> ElaboratedInstallPlan -> IO BuildStatusMap #

Do the dry run pass. This is a prerequisite of `rebuildTargets`.

It gives us the `BuildStatusMap`. This should be used with `improveInstallPlanWithUpToDatePackages` to give an improved version of the `ElaboratedInstallPlan` with packages switched to the `Installed` state when we find that they're already up to date.

improveInstallPlanWithUpToDatePackages :: BuildStatusMap -> ElaboratedInstallPlan -> ElaboratedInstallPlan #

## Build status

This is the detailed status information we get from the dry run.

type BuildStatusMap = Map UnitId BuildStatus #

The `BuildStatus` of every package in the `ElaboratedInstallPlan`.

This is used as the result of the dry-run of building an install plan.

data BuildStatus #

The build status for an individual package is the state that the package is in prior to initiating a (re)build.

This should not be confused with a `BuildResult` which is the result after successfully building a package.

It serves two purposes:

- For dry-run output, it lets us explain to the user if and why a package is going to be (re)built.
- It tell us what step to start or resume building from, and carries enough information for us to be able to do so.

Constructors

BuildStatusPreExisting | The package is in the `PreExisting` state, so does not need building.
BuildStatusInstalled | The package is in the `Installed` state, so does not need building.
BuildStatusDownload | The package has not been downloaded yet, so it will have to be downloaded, unpacked and built.
BuildStatusUnpack FilePath | The package has not been unpacked yet, so it will have to be unpacked and built.
BuildStatusRebuild FilePath BuildStatusRebuild | The package exists in a local dir already, and just needs building or rebuilding. So this can only happen for `BuildInplaceOnly` style packages.
BuildStatusUpToDate BuildResult | The package exists in a local dir already, and is fully up to date. So this package can be put into the `Installed` state and it does not need to be built.

data BuildStatusRebuild #

For a package that is going to be built or rebuilt, the state it's in now.

So again, this tells us why a package needs to be rebuilt and what build phases need to be run. The `MonitorChangedReason` gives us details like which file changed, which is mainly for high verbosity debug output.

Constructors

BuildStatusConfigure (MonitorChangedReason ()) | The package configuration changed, so the configure and build phases needs to be (re)run.
BuildStatusBuild (Maybe (Maybe InstalledPackageInfo)) BuildReason | The configuration has not changed but the build phase needs to be rerun. We record the reason the (re)build is needed. The optional registration info here tells us if we've registered the package already, or if we still need to do that after building. `Just Nothing` indicates that we know that no registration is necessary (e.g., executable.)

data BuildReason #

Constructors

BuildReasonDepsRebuilt | The dependencies of this package have been (re)built so the build phase needs to be rerun.
BuildReasonFilesChanged (MonitorChangedReason ()) | Changes in files within the package (or first run or corrupt cache)
BuildReasonExtraTargets (Set ComponentName) | An important special case is that no files have changed but the set of components the user asked to build has changed. We track the set of components we have built, which of course only grows (until some other change resets it). The `Set `ComponentName`` is the set of components we have built previously. When we update the monitor we take the union of the ones we have built previously with the ones the user has asked for this time and save those. See `updatePackageBuildFileMonitor`.
BuildReasonEphemeralTargets | Although we're not going to build any additional targets as a whole, we're going to build some part of a component or run a repl or any other action that does not result in additional persistent artifacts.

data MonitorChangedReason a #

What kind of change `checkFileMonitorChanged` detected.

Constructors

MonitoredFileChanged FilePath | One of the files changed (existence, file type, mtime or file content, depending on the `MonitorFilePath` in question)
MonitoredValueChanged a | The pure input value changed. The previous cached key value is also returned. This is sometimes useful when using a `fileMonitorKeyValid` function that is not simply `(==)`, when invalidation can be partial. In such cases it can make sense to `updateFileMonitor` with a key value that's a combination of the new and old (e.g. set union).
MonitorFirstRun | There was no saved monitor state, cached value etc. Ie the file for the `FileMonitor` does not exist.
MonitorCorruptCache | There was existing state, but we could not read it. This typically happens when the code has changed compared to an existing `FileMonitor` cache file and type of the input value or cached value has changed such that we cannot decode the values. This is completely benign as we can treat is just as if there were no cache file and re-run.

#### Instances

Instances details

Functor MonitorChangedReason # |
Instance details Defined in Distribution.Client.FileMonitor Methods fmap :: (a -> b) -> MonitorChangedReason a -> MonitorChangedReason b # (<$) :: a -> MonitorChangedReason b -> MonitorChangedReason a #
Show a => Show (MonitorChangedReason a) # |
Instance details Defined in Distribution.Client.FileMonitor Methods showsPrec :: Int -> MonitorChangedReason a -> ShowS # show :: MonitorChangedReason a -> String # showList :: [MonitorChangedReason a] -> ShowS #
Eq a => Eq (MonitorChangedReason a) # |
Instance details Defined in Distribution.Client.FileMonitor Methods (==) :: MonitorChangedReason a -> MonitorChangedReason a -> Bool # (/=) :: MonitorChangedReason a -> MonitorChangedReason a -> Bool #

buildStatusToString :: BuildStatus -> String #

This is primarily here for debugging. It's not actually used anywhere.

# Build phase

Now we actually execute the plan.

rebuildTargets :: Verbosity -> ProjectConfig -> DistDirLayout -> StoreDirLayout -> ElaboratedInstallPlan -> ElaboratedSharedConfig -> BuildStatusMap -> BuildTimeSettings -> IO BuildOutcomes #

Build things for real.

It requires the `BuildStatusMap` gathered by `rebuildTargetsDryRun`.

## Build outcomes

This is the outcome for each package of executing the plan. For each package, did the build succeed or fail?

type BuildOutcomes = Map UnitId BuildOutcome #

A summary of the outcome for building a whole set of packages.

type BuildOutcome = Either BuildFailure BuildResult #

A summary of the outcome for building a single package: either success or failure.

data BuildResult #

Information arising from successfully building a single package.

Constructors

BuildResult |
Fields buildResultDocs :: DocsResult buildResultTests :: TestsResult buildResultLogFile :: Maybe FilePath

#### Instances

Instances details

Show BuildResult # |
Instance details Defined in Distribution.Client.ProjectBuilding.Types Methods showsPrec :: Int -> BuildResult -> ShowS # show :: BuildResult -> String # showList :: [BuildResult] -> ShowS #

data BuildFailure #

Information arising from the failure to build a single package.

Constructors

BuildFailure |
Fields buildFailureLogFile :: Maybe FilePath buildFailureReason :: BuildFailureReason

#### Instances

Instances details

Exception BuildFailure # |
Instance details Defined in Distribution.Client.ProjectBuilding.Types Methods toException :: BuildFailure -> SomeException # fromException :: SomeException -> Maybe BuildFailure # displayException :: BuildFailure -> String # backtraceDesired :: BuildFailure -> Bool #
Show BuildFailure # |
Instance details Defined in Distribution.Client.ProjectBuilding.Types Methods showsPrec :: Int -> BuildFailure -> ShowS # show :: BuildFailure -> String # showList :: [BuildFailure] -> ShowS #

data BuildFailureReason #

Detail on the reason that a package failed to build.

Constructors

DependentFailed PackageId |
GracefulFailure String |
DownloadFailed SomeException |
UnpackFailed SomeException |
ConfigureFailed SomeException |
BuildFailed SomeException |
ReplFailed SomeException |
HaddocksFailed SomeException |
TestsFailed SomeException |
BenchFailed SomeException |
InstallFailed SomeException |

#### Instances

Instances details

Show BuildFailureReason # |
Instance details Defined in Distribution.Client.ProjectBuilding.Types Methods showsPrec :: Int -> BuildFailureReason -> ShowS # show :: BuildFailureReason -> String # showList :: [BuildFailureReason] -> ShowS #