Distribution.Client.RebuildMonad

A monad layered on top of IO to help with re-running actions when the input files and values they depend on change. The crucial operations are rerunIfChanged and monitorFiles.

Run a Rebuild IO action.

Run a Rebuild IO action.

The root that relative paths are interpreted as being relative to.

Use this within the body action of rerunIfChanged to declare that the action depends on the given files. This can be based on what the action actually did. It is these files that will be checked for changes next time rerunIfChanged is called for that FileMonitor.

Relative paths are interpreted as relative to an implicit root, ultimately passed in to runRebuild.

A description of a file (or set of files) to monitor for changes.

Where file paths are relative they are relative to a common directory (e.g. project root), not necessarily the process current directory.

Monitor a single file for changes, based on its modification time. The monitored file is considered to have changed if it no longer exists or if its modification time has changed.

Monitor a single file for changes, based on its modification time and content hash. The monitored file is considered to have changed if it no longer exists or if its modification time and content hash have changed.

Monitor a single non-existent file for changes. The monitored file is considered to have changed if it exists.

Monitor a single directory for changes, based on its modification time. The monitored directory is considered to have changed if it no longer exists or if its modification time has changed.

Monitor a single non-existent directory for changes. The monitored directory is considered to have changed if it exists.

Monitor a single directory for existence. The monitored directory is considered to have changed only if it no longer exists.

Monitor a single file or directory for changes, based on its modification time. The monitored file is considered to have changed if it no longer exists or if its modification time has changed.

Creates a list of files to monitor when you search for a file which unsuccessfully looked in notFoundAtPaths before finding it at foundAtPath.

Similar to monitorFileSearchPath, but also instructs us to monitor the hash of the found file.

A monitor for detecting changes to a set of files. It can be used to efficiently test if any of a set of files (specified individually or by glob patterns) has changed since some snapshot. In addition, it also checks for changes in a value (of type a), and when there are no changes in either it returns a saved value (of type b).

The main use case looks like this: suppose we have some expensive action that depends on certain pure inputs and reads some set of files, and produces some pure result. We want to avoid re-running this action when it would produce the same result. So we need to monitor the files the action looked at, the other pure input values, and we need to cache the result. Then at some later point, if the input value didn't change, and none of the files changed, then we can re-use the cached result rather than re-running the action.

This can be achieved using a FileMonitor. Each FileMonitor instance saves state in a disk file, so the file for that has to be specified, making sure it is unique. The pattern is to use checkFileMonitorChanged to see if there's been any change. If there is, re-run the action, keeping track of the files, then use updateFileMonitor to record the current set of files to monitor, the current input value for the action, and the result of the action.

The typical occurrence of this pattern is captured by rerunIfChanged and the Rebuild monad. More complicated cases may need to use checkFileMonitorChanged and updateFileMonitor directly.

Define a new file monitor.

It's best practice to define file monitor values once, and then use the same value for checkFileMonitorChanged and updateFileMonitor as this ensures you get the same types a and b for reading and writing.

The path of the file monitor itself must be unique because it keeps state on disk and these would clash.

This captures the standard use pattern for a FileMonitor: given a monitor, an action and the input value the action depends on, either re-run the action to get its output, or if the value and files the action depends on have not changed then return a previously cached action result.

The result is still in the Rebuild monad, so these can be nested.

Do not share FileMonitors between different uses of rerunIfChanged.

When using rerunIfChanged for each element of a list of actions, it is sometimes the case that each action needs to make use of some resource. e.g.

sequence
  [ rerunIfChanged verbosity monitor key $ do
      resource <- mkResource
      ... -- use the resource
  | ... ]

For efficiency one would like to share the resource between the actions but the straightforward way of doing this means initialising it every time even when no actions need re-running.

resource <- mkResource
sequence
  [ rerunIfChanged verbosity monitor key $ do
      ... -- use the resource
  | ... ]

This utility allows one to get the best of both worlds:

getResource <- delayInitSharedResource mkResource
sequence
  [ rerunIfChanged verbosity monitor key $ do
      resource <- getResource
      ... -- use the resource
  | ... ]

Much like delayInitSharedResource but for a keyed set of resources.

getResource <- delayInitSharedResource mkResource
sequence
  [ rerunIfChanged verbosity monitor key $ do
      resource <- getResource key
      ... -- use the resource
  | ... ]

Utility to match a file glob against the file system, starting from a given root directory. The results are all relative to the given root.

Since this operates in the Rebuild monad, it also monitors the given glob for changes.

Monitor a directory as in monitorDirectory if it currently exists or as monitorNonExistentDirectory if it does not.

Like doesFileExist, but in the Rebuild monad. This does NOT track the contents of FilePath; use need in that case.

Monitor a single file

Monitor a file if it exists; otherwise check for when it gets created. This is a bit better for recompilation avoidance because sometimes users give bad package metadata, and we don't want to repeatedly rebuild in this case (which we would if we need'ed a non-existent file).

Like findFileWithExtension, but in the Rebuild monad.

Like findFirstFile, but in the Rebuild monad.

Like findFile, but in the Rebuild monad.