Pier.Core.Artifact

A generic approach to building and caching file outputs.

This is a layer on top of Shake which enables build actions to be written in a "forwards" style. For example:

runPier $ action $ do
    contents <- lines <$> readArtifactA (externalFile "result.txt")
    let result = "result.tar"
    runCommand (output result)
       $ foldMap input contents
         <> prog "tar" (["-cf", result] ++ map pathIn contents)

This approach generally leads to simpler logic than backwards-defined build systems such as make or (normal) Shake, where each step of the build logic must be written as a new build rule.

Inputs and outputs of a command must be declared up-front, using the input and output functions respectively. This enables isolated, deterministic build steps which are each run in their own temporary directory.

Output files are stored in the location

_pier/artifact/HASH/path/to/file

where HASH is a string that uniquely determines the action generating that file. In particular, there is no need to worry about choosing distinct names for outputs of different commands.

Note that Forward has similar motivation to this module, but instead uses fsatrace to detect what files changed after the fact. Unfortunately, that approach is not portable. Additionally, it makes it difficult to isolate steps and make the build more reproducible (for example, to prevent the output of one step being mutated by a later one) since every output file could potentially be an input to every action. Finally, by explicitly declaring outputs we can detect sooner when a command doesn't produce the files that we expect.

Rules

artifactRules :: HandleTemps -> Rules ()

Artifact

data Artifact

An Artifact is a file or folder that was created by a build command.

Instances

Eq Artifact

Methods

(==) :: Artifact -> Artifact -> Bool

(/=) :: Artifact -> Artifact -> Bool

Ord Artifact

Methods

compare :: Artifact -> Artifact -> Ordering

(<) :: Artifact -> Artifact -> Bool

(<=) :: Artifact -> Artifact -> Bool

(>) :: Artifact -> Artifact -> Bool

(>=) :: Artifact -> Artifact -> Bool

max :: Artifact -> Artifact -> Artifact

min :: Artifact -> Artifact -> Artifact

Show Artifact

Methods

showsPrec :: Int -> Artifact -> ShowS

show :: Artifact -> String

showList :: [Artifact] -> ShowS

Generic Artifact

Associated Types

type Rep Artifact :: * -> *

Methods

from :: Artifact -> Rep Artifact x

to :: Rep Artifact x -> Artifact

NFData Artifact

Methods

rnf :: Artifact -> ()

Binary Artifact

Methods

put :: Artifact -> Put

get :: Get Artifact

putList :: [Artifact] -> Put

Hashable Artifact

Methods

hashWithSalt :: Int -> Artifact -> Int

hash :: Artifact -> Int

type Rep Artifact

type Rep Artifact

externalFile :: FilePath -> Artifact

Create an Artifact from an input file to the build (for example, a source file created by the user).

If it is a relative path, changes to the file will cause rebuilds of Commands and Rules that dependended on it.

(/>) :: Artifact -> FilePath -> Artifact infixr 5

Create a reference to a sub-file of the given Artifact, which must refer to a directory.

replaceArtifactExtension :: Artifact -> String -> Artifact

Replace the extension of an Artifact. In particular,

pathIn (replaceArtifactExtension f ext) == replaceExtension (pathIn f) ext@

readArtifact :: Artifact -> Action String

Read the contents of an Artifact.

readArtifactB :: Artifact -> Action ByteString

doesArtifactExist :: Artifact -> Action Bool

matchArtifactGlob :: Artifact -> FilePath -> Action [FilePath]

unfreezeArtifacts :: IO ()

Make all artifacts user-writable, so they can be deleted by `clean-all`.

callArtifact :: HandleTemps -> Set Artifact -> Artifact -> [String] -> IO ()

Creating artifacts

writeArtifact :: FilePath -> String -> Action Artifact

runCommand :: Output t -> Command -> Action t

Run the given command, capturing the specified outputs.

runCommand_ :: Command -> Action ()

Run the given command without capturing its output. Can be used to check consistency of the outputs of previous commands.

runCommandStdout :: Command -> Action String

data Command

A hermetic build step. Consists of a sequence of calls to message, 'prog'/'progA'/'progTemp', andor shadow, which may be combined using <>mappend. Also specifies the input Artifacts that are used by those commands.

Instances

Eq Command

Methods

(==) :: Command -> Command -> Bool

(/=) :: Command -> Command -> Bool

Generic Command

Associated Types

type Rep Command :: * -> *

Methods

from :: Command -> Rep Command x

to :: Rep Command x -> Command

Semigroup Command

Methods

(<>) :: Command -> Command -> Command

sconcat :: NonEmpty Command -> Command

stimes :: Integral b => b -> Command -> Command

Monoid Command

Methods

mempty :: Command

mappend :: Command -> Command -> Command

mconcat :: [Command] -> Command

NFData Command

Methods

rnf :: Command -> ()

Binary Command

Methods

put :: Command -> Put

get :: Get Command

putList :: [Command] -> Put

Hashable Command

Methods

hashWithSalt :: Int -> Command -> Int

hash :: Command -> Int

type Rep Command

type Rep Command

message :: String -> Command

Prints a status message for the user when this command runs.

Command outputs

data Output a

The output of a given command.

Multiple outputs may be combined using the Applicative instance.

Instances

Functor Output

Methods

fmap :: (a -> b) -> Output a -> Output b

(<$) :: a -> Output b -> Output a

Applicative Output

Methods

pure :: a -> Output a

(<*>) :: Output (a -> b) -> Output a -> Output b

liftA2 :: (a -> b -> c) -> Output a -> Output b -> Output c

(*>) :: Output a -> Output b -> Output b

(<*) :: Output a -> Output b -> Output a

output :: FilePath -> Output Artifact

Register a single output of a command.

The input must be a relative path and nontrivial (i.e., not "." or "").

Command inputs

input :: Artifact -> Command

Specify that an Artifact should be made available to program calls within this Command.

Note that the order does not matter; `input f <> cmd === cmd <> input f`.

inputs :: Set Artifact -> Command

Specify that a set of Artifacts should be made available to program calls within this Command.

inputList :: [Artifact] -> Command

shadow :: Artifact -> FilePath -> Command

Make a "shadow" copy of the given input artifact's by create a symlink of this artifact (if it is a file) or of each sub-file (transitively, if it is a directory).

The result may be captured as output, for example when grouping multiple outputs of separate commands into a common directory structure.

groupFiles :: Artifact -> [(FilePath, FilePath)] -> Action Artifact

Group source files by shadowing into a single directory.

Running commands

prog :: String -> [String] -> Command

Run an external command-line program with the given arguments.

progA :: Artifact -> [String] -> Command

Run an artifact as an command-line program with the given arguments.

progTemp :: FilePath -> [String] -> Command

Run a command-line program with the given arguments, where the program was created by a previous program.

pathIn :: Artifact -> FilePath

Returns the relative path to an Artifact within the sandbox, when provided to a Command by input.

withCwd :: FilePath -> Command -> Command

Runs a command within the given (relative) directory.

createDirectoryA :: FilePath -> Command