Build.Task.Opaque

Opaque monadic tasks, whose inputs and outputs can be dynamic.

Documentation

type Variable = String

Environment variables are identified by names.

data Key a where

A collection of keys for accessing files, environment variables, and contents of directories. Directories are somewhat magic, because their values are derived from File keys, i.e. creating a new file in a directory requires updating the the corresponding Dir key.

Constructors

File

Fields

• :: FilePath
• -> Key String

  File contents.

Env

Fields

• :: Variable
• -> Key String

  Environment variable.

Dir

Fields

• :: FilePath
• -> Key [FilePath]

  Directory contents.

Instances

Show (LogEntry Key)

Defined in Build.Task.Opaque

Methods

showsPrec :: Int -> LogEntry Key -> ShowS

show :: LogEntry Key -> String

showList :: [LogEntry Key] -> ShowS

type Get k f = forall a. k a -> f a

Read a key's value in a computation context f.

type Put k f = forall a. k a -> a -> f ()

Write a key's value in a computation context f. Note: the type can be changed to forall a. k a -> f a -> f a to allow for static analysis of applicative and selective build tasks, since we cannot have a in a static context f, e.g. in Const. See more details in Section 5.3 of this paper: https://www.staff.ncl.ac.uk/andrey.mokhov/selective-functors.pdf.

type Task k a = forall f. Monad f => Get k f -> Put k f -> f a

A build task is a stateful computation in a monadic context f that is given two callbacks: for reading and writing values to a key/value store.

type TaskName = String

A unique task identifier, e.g. the path to the corresponding build script.

data NamedTask k

A task along with its unique identifier.

Constructors

NamedTask

Fields

• taskName :: TaskName
• task :: Task k ()

type Tasks k = [NamedTask k]

A collection of build tasks using the same read and write interface.

type BlackBox = Task Key ()

An example type of "black box" build tasks: we can only find out what they read and write by executing them in a monadic context.

type BlackBoxes = Tasks Key

Multiple black boxes, e.g. a collection of build scripts lying around.

tasks :: BlackBoxes

An example collection of black boxes.

build :: BlackBox

A typical build script that compiles a couple of C files, possibly depending on some header files, and then links the resulting objects into an executable.

release :: BlackBox

A script for packaging the contents of the directory out in an archive. Note that if called prematurely, it will miss some of the release files and will succeed, yielding an incomplete archive. The task will therefore need to be rerun whenever the key Dir "out" is updated.

compile :: FilePath -> FilePath -> BlackBox

Compile a C source file, possibly including the lib.h header.

link :: FilePath -> FilePath -> BlackBox

Link object files in a given directory, producing an executable. Note that this task can fail if run prematurely i.e. when some object files have not yet been placed in the obj directory, since some symbols will be undefined.

data LogEntry k where

A task execution log entry, recording either a read from a key and the obtained value, or a write to a key, along with the written value.

Constructors

GetEntry :: k a -> a -> LogEntry k

PutEntry :: k a -> a -> LogEntry k

Instances

Show (LogEntry Key)

Defined in Build.Task.Opaque

Methods

showsPrec :: Int -> LogEntry Key -> ShowS

show :: LogEntry Key -> String

showList :: [LogEntry Key] -> ShowS

type Log k = [LogEntry k]

A log is a sequence of log entries, in the execution order.

hasWrongGet :: Log Key -> Key a -> a -> Bool

Check if a log contains a GetEntry for a given Key. Useful to detect if a task has a certain input dependency.

execute :: forall m k. Monad m => Get k m -> Put k m -> Task k () -> m (Log k)

Execute a monadic task using given callbacks Get and Put, logging all reads and writes.

newtype Store

An association of keys to values.

Constructors

Store

Fields

• getValue :: forall a. Key a -> a

putValue :: Key a -> a -> Store -> Store

exampleStore :: Store

An example store with the following contents:

File "src/a.c" -> "a" File "src/b.c" -> "b...#include lib.h..." File "obj/main.o" -> "...main..." File "lib/lib.h" -> "lib..." File "out/README" -> "This is a README..." Env LIBDIR -> "lib" Dir "obj" -> ["main.o"] Dir "out" -> [README]

type Graph = TaskName -> Maybe (Log Key)

Known information about build task dependencies.

blindBuild :: BlackBoxes -> Store -> Graph -> (Store, Graph)

A build system that builds a collection of black box tasks by executing them blindly, and recording the resulting dependencies.

type ShowKey k = forall a. k a -> String

A way to show the name of a key.

showKey :: ShowKey Key

A simple pretty-printer for the data type Key.

showValue :: Key a -> a -> String

Show a value corresponding to a key, extracting an appropriate Show instance from it.

getIO :: Get Key IO

A Get in IO for GHCi experiments.

putIO :: Put Key IO

A Put in IO for GHCi experiments.