Development.Shake.Command

This module provides functions for calling command line programs, primarily command and cmd. As a simple example:

command [] "gcc" ["-c",myfile]

The functions from this module are now available directly from Development.Shake. You should only need to import this module if you are using the cmd function in the IO monad.

Documentation

command :: (Partial, CmdResult r) => [CmdOption] -> String -> [String] -> Action r

Execute a system command. Before running command make sure you need any files that are used by the command.

This function takes a list of options (often just [], see CmdOption for the available options), the name of the executable (either a full name, or a program on the $PATH) and a list of arguments. The result is often (), but can be a tuple containg any of Stdout, Stderr and Exit. Some examples:

command_ [] "gcc" ["-c","myfile.c"]                          -- compile a file, throwing an exception on failure
Exit c <- command [] "gcc" ["-c",myfile]                     -- run a command, recording the exit code
(Exit c, Stderr err) <- command [] "gcc" ["-c","myfile.c"]   -- run a command, recording the exit code and error output
Stdout out <- command [] "gcc" ["-MM","myfile.c"]            -- run a command, recording the output
command_ [Cwd "generated"] "gcc" ["-c",myfile]               -- run a command in a directory

Unless you retrieve the ExitCode using Exit, any ExitFailure will throw an error, including the Stderr in the exception message. If you capture the Stdout or Stderr, that stream will not be echoed to the console, unless you use the option EchoStdout or EchoStderr.

If you use command inside a do block and do not use the result, you may get a compile-time error about being unable to deduce CmdResult. To avoid this error, use command_.

By default the stderr stream will be captured for use in error messages, and also echoed. To only echo pass WithStderr False, which causes no streams to be captured by Shake, and certain programs (e.g. gcc) to detect they are running in a terminal.

command_ :: Partial => [CmdOption] -> String -> [String] -> Action ()

A version of command where you do not require any results, used to avoid errors about being unable to deduce CmdResult.

cmd :: (Partial, CmdArguments args) => args :-> Action r

Build or execute a system command. Before using cmd to run a command, make sure you need any files that are used by the command.

• String arguments are treated as a list of whitespace separated arguments.
• [String] arguments are treated as a list of literal arguments.
• CmdOption arguments are used as options.
• CmdArgument arguments, which can be built by cmd itself, are spliced into the containing command.

Typically only string literals should be passed as String arguments. When using variables prefer [myvar] so that if myvar contains spaces they are properly escaped.

As some examples, here are some calls, and the resulting command string:

cmd_ "git log --pretty=" "oneline"           -- git log --pretty= oneline
cmd_ "git log --pretty=" ["oneline"]         -- git log --pretty= oneline
cmd_ "git log" ("--pretty=" ++ "oneline")    -- git log --pretty=oneline
cmd_ "git log" ("--pretty=" ++ "one line")   -- git log --pretty=one line
cmd_ "git log" ["--pretty=" ++ "one line"]   -- git log "--pretty=one line"

More examples, including return values, see this translation of the examples given for the command function:

cmd_ "gcc -c myfile.c"                                       -- compile a file, throwing an exception on failure
Exit c <- cmd "gcc -c" [myfile]                              -- run a command, recording the exit code
(Exit c, Stderr err) <- cmd "gcc -c myfile.c"                -- run a command, recording the exit code and error output
Stdout out <- cmd "gcc -MM myfile.c"                         -- run a command, recording the output
cmd (Cwd "generated") "gcc -c" [myfile] :: Action ()         -- run a command in a directory

let gccCommand = cmd "gcc -c" :: CmdArgument                 -- build a sub-command. cmd can return CmdArgument values as well as execute commands
cmd (Cwd "generated") gccCommand [myfile]                 -- splice that command into a greater command

If you use cmd inside a do block and do not use the result, you may get a compile-time error about being unable to deduce CmdResult. To avoid this error, use cmd_. If you enable OverloadedStrings or OverloadedLists you may have to give type signatures to the arguments, or use the more constrained command instead.

The cmd function can also be run in the IO monad, but then Traced is ignored and command lines are not echoed. As an example:

cmd (Cwd "generated") Shell "gcc -c myfile.c" :: IO ()

cmd_ :: (Partial, CmdArguments args, Unit args) => args :-> Action ()

See cmd. Same as cmd except with a unit result. cmd is to cmd_ as command is to command_.

unit :: m () -> m ()

The identity function which requires the inner argument to be (). Useful for functions with overloaded return types.

\(x :: Maybe ()) -> unit x == x

newtype CmdArgument

The arguments to cmd - see cmd for examples and semantics.

Constructors

CmdArgument [Either CmdOption String]

Instances

Eq CmdArgument

Defined in Development.Shake.Command

Methods

(==) :: CmdArgument -> CmdArgument -> Bool

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

Show CmdArgument

Defined in Development.Shake.Command

Methods

showsPrec :: Int -> CmdArgument -> ShowS

show :: CmdArgument -> String

showList :: [CmdArgument] -> ShowS

Semigroup CmdArgument

Defined in Development.Shake.Command

Methods

(<>) :: CmdArgument -> CmdArgument -> CmdArgument

sconcat :: NonEmpty CmdArgument -> CmdArgument

stimes :: Integral b => b -> CmdArgument -> CmdArgument

Monoid CmdArgument

Defined in Development.Shake.Command

Methods

mempty :: CmdArgument

mappend :: CmdArgument -> CmdArgument -> CmdArgument

mconcat :: [CmdArgument] -> CmdArgument

IsCmdArgument CmdArgument

Defined in Development.Shake.Command

Methods

toCmdArgument :: CmdArgument -> CmdArgument

CmdArguments CmdArgument

Defined in Development.Shake.Command

Methods

cmdArguments :: CmdArgument -> CmdArgument

class CmdArguments t where

The arguments to cmd - see cmd for examples and semantics.

Methods

cmdArguments :: Partial => CmdArgument -> t

Arguments to cmd

Instances

CmdArguments CmdArgument

Defined in Development.Shake.Command

Methods

cmdArguments :: CmdArgument -> CmdArgument

CmdResult r => CmdArguments (IO r)

Defined in Development.Shake.Command

Methods

cmdArguments :: CmdArgument -> IO r

CmdResult r => CmdArguments (Action r)

Defined in Development.Shake.Command

Methods

cmdArguments :: CmdArgument -> Action r

(IsCmdArgument a, CmdArguments r) => CmdArguments (a -> r)

Defined in Development.Shake.Command

Methods

cmdArguments :: CmdArgument -> a -> r

class IsCmdArgument a where

Class to convert an a to a CmdArgument

Methods

toCmdArgument :: a -> CmdArgument

Conversion to a CmdArgument

Instances

IsCmdArgument ()

Defined in Development.Shake.Command

Methods

toCmdArgument :: () -> CmdArgument

IsCmdArgument String

Defined in Development.Shake.Command

Methods

toCmdArgument :: String -> CmdArgument

IsCmdArgument CmdOption

Defined in Development.Shake.Command

Methods

toCmdArgument :: CmdOption -> CmdArgument

IsCmdArgument CmdArgument

Defined in Development.Shake.Command

Methods

toCmdArgument :: CmdArgument -> CmdArgument

IsCmdArgument [String]

Defined in Development.Shake.Command

Methods

toCmdArgument :: [String] -> CmdArgument

IsCmdArgument [CmdOption]

Defined in Development.Shake.Command

Methods

toCmdArgument :: [CmdOption] -> CmdArgument

IsCmdArgument a => IsCmdArgument (Maybe a)

Defined in Development.Shake.Command

Methods

toCmdArgument :: Maybe a -> CmdArgument

IsCmdArgument (NonEmpty String)

Defined in Development.Shake.Command

Methods

toCmdArgument :: NonEmpty String -> CmdArgument

type (:->) a t = a

A type annotation, equivalent to the first argument, but in variable argument contexts, gives a clue as to what return type is expected (not actually enforced).

newtype Stdout a

Collect the stdout of the process. If used, the stdout will not be echoed to the terminal, unless you include EchoStdout. The value type may be either String, or either lazy or strict ByteString.

Note that most programs end their output with a trailing newline, so calling ghc --numeric-version will result in Stdout of "6.8.3\n". If you want to automatically trim the resulting string, see StdoutTrim.

Constructors

Stdout

Fields

• fromStdout :: a

Instances

CmdString a => CmdResult (Stdout a)

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> Stdout a)

newtype StdoutTrim a

Like Stdout but remove all leading and trailing whitespaces.

Constructors

StdoutTrim

Fields

• fromStdoutTrim :: a

Instances

CmdString a => CmdResult (StdoutTrim a)

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> StdoutTrim a)

newtype Stderr a

Collect the stderr of the process. If used, the stderr will not be echoed to the terminal, unless you include EchoStderr. The value type may be either String, or either lazy or strict ByteString.

Constructors

Stderr

Fields

• fromStderr :: a

Instances

CmdString a => CmdResult (Stderr a)

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> Stderr a)

newtype Stdouterr a

Collect the stdout and stderr of the process. If used, the stderr and stdout will not be echoed to the terminal, unless you include EchoStdout and EchoStderr. The value type may be either String, or either lazy or strict ByteString.

Constructors

Stdouterr

Fields

• fromStdouterr :: a

Instances

CmdString a => CmdResult (Stdouterr a)

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> Stdouterr a)

newtype Exit

Collect the ExitCode of the process. If you do not collect the exit code, any ExitFailure will cause an exception.

Constructors

Exit

Fields

• fromExit :: ExitCode

Instances

CmdResult Exit

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> Exit)

newtype Process

Collect the ProcessHandle of the process. If you do collect the process handle, the command will run asyncronously and the call to cmd / command will return as soon as the process is spawned. Any Stdout / Stderr captures will return empty strings.

Constructors

Process

Fields

• fromProcess :: ProcessHandle

Instances

CmdResult Process

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> Process)

newtype CmdTime

Collect the time taken to execute the process. Can be used in conjunction with CmdLine to write helper functions that print out the time of a result.

timer :: (CmdResult r, MonadIO m) => (forall r . CmdResult r => m r) -> m r
timer act = do
    (CmdTime t, CmdLine x, r) <- act
    liftIO $ putStrLn $ "Command " ++ x ++ " took " ++ show t ++ " seconds"
    pure r

run :: IO ()
run = timer $ cmd "ghc --version"

Constructors

CmdTime

Fields

• fromCmdTime :: Double

Instances

CmdResult CmdTime

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> CmdTime)

newtype CmdLine

Collect the command line used for the process. This command line will be approximate - suitable for user diagnostics, but not for direct execution.

Constructors

CmdLine

Fields

• fromCmdLine :: String

Instances

CmdResult CmdLine

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> CmdLine)

data FSATrace a

The results produced by fsatrace. All files will be absolute paths. You can get the results for a cmd by requesting a value of type [FSATrace].

Constructors

FSAWrite a

Writing to a file

FSARead a

Reading from a file

FSADelete a

Deleting a file

FSAMove a a

Moving, arguments destination, then source

FSAQuery a

Querying/stat on a file

FSATouch a

Touching a file

Instances

Functor FSATrace

Defined in Development.Shake.Command

Methods

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

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

Eq a => Eq (FSATrace a)

Defined in Development.Shake.Command

Methods

(==) :: FSATrace a -> FSATrace a -> Bool

(/=) :: FSATrace a -> FSATrace a -> Bool

Data a => Data (FSATrace a)

Defined in Development.Shake.Command

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> FSATrace a -> c (FSATrace a)

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (FSATrace a)

toConstr :: FSATrace a -> Constr

dataTypeOf :: FSATrace a -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (FSATrace a))

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (FSATrace a))

gmapT :: (forall b. Data b => b -> b) -> FSATrace a -> FSATrace a

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> FSATrace a -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> FSATrace a -> r

gmapQ :: (forall d. Data d => d -> u) -> FSATrace a -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> FSATrace a -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> FSATrace a -> m (FSATrace a)

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> FSATrace a -> m (FSATrace a)

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> FSATrace a -> m (FSATrace a)

Ord a => Ord (FSATrace a)

Defined in Development.Shake.Command

Methods

compare :: FSATrace a -> FSATrace a -> Ordering

(<) :: FSATrace a -> FSATrace a -> Bool

(<=) :: FSATrace a -> FSATrace a -> Bool

(>) :: FSATrace a -> FSATrace a -> Bool

(>=) :: FSATrace a -> FSATrace a -> Bool

max :: FSATrace a -> FSATrace a -> FSATrace a

min :: FSATrace a -> FSATrace a -> FSATrace a

Show a => Show (FSATrace a)

Defined in Development.Shake.Command

Methods

showsPrec :: Int -> FSATrace a -> ShowS

show :: FSATrace a -> String

showList :: [FSATrace a] -> ShowS

CmdResult [FSATrace FilePath]

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> [FSATrace FilePath])

CmdResult [FSATrace ByteString]

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> [FSATrace ByteString])

class CmdResult a

A class for specifying what results you want to collect from a process. Values are formed of Stdout, Stderr, Exit and tuples of those.

Minimal complete definition

cmdResult

Instances

CmdResult ()

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> ())

CmdResult ExitCode

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> ExitCode)

CmdResult ProcessHandle

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> ProcessHandle)

CmdResult CmdLine

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> CmdLine)

CmdResult CmdTime

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> CmdTime)

CmdResult Process

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> Process)

CmdResult Exit

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> Exit)

CmdResult [FSATrace FilePath]

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> [FSATrace FilePath])

CmdResult [FSATrace ByteString]

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> [FSATrace ByteString])

CmdString a => CmdResult (Stdouterr a)

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> Stdouterr a)

CmdString a => CmdResult (Stderr a)

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> Stderr a)

CmdString a => CmdResult (StdoutTrim a)

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> StdoutTrim a)

CmdString a => CmdResult (Stdout a)

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> Stdout a)

(CmdResult x1, CmdResult x2) => CmdResult (x1, x2)

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> (x1, x2))

(CmdResult x1, CmdResult x2, CmdResult x3) => CmdResult (x1, x2, x3)

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> (x1, x2, x3))

(CmdResult x1, CmdResult x2, CmdResult x3, CmdResult x4) => CmdResult (x1, x2, x3, x4)

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> (x1, x2, x3, x4))

(CmdResult x1, CmdResult x2, CmdResult x3, CmdResult x4, CmdResult x5) => CmdResult (x1, x2, x3, x4, x5)

Defined in Development.Shake.Command

Methods

cmdResult :: ([Result], [Result] -> (x1, x2, x3, x4, x5))

class CmdString a

The allowable String-like values that can be captured.

Minimal complete definition

cmdString

Instances

CmdString ()

Defined in Development.Shake.Command

Methods

cmdString :: (Str, Str -> ())

CmdString String

Defined in Development.Shake.Command

Methods

cmdString :: (Str, Str -> String)

CmdString ByteString

Defined in Development.Shake.Command

Methods

cmdString :: (Str, Str -> ByteString)

CmdString ByteString

Defined in Development.Shake.Command

Methods

cmdString :: (Str, Str -> ByteString)

data CmdOption

Options passed to command or cmd to control how processes are executed.

Constructors

Cwd FilePath

Change the current directory in the spawned process. By default uses this processes current directory. Successive Cwd options are joined together, to change into nested directories.

Env [(String, String)]

Change the environment variables in the spawned process. By default uses this processes environment.

AddEnv String String

Add an environment variable in the child process.

RemEnv String

Remove an environment variable from the child process.

AddPath [String] [String]

Add some items to the prefix and suffix of the $PATH variable.

Stdin String

Given as the stdin of the spawned process. By default the stdin is inherited.

StdinBS ByteString

Given as the stdin of the spawned process.

FileStdin FilePath

Take the stdin from a file.

Shell

Pass the command to the shell without escaping - any arguments will be joined with spaces. By default arguments are escaped properly.

BinaryPipes

Treat the stdin/stdout/stderr messages as binary. By default String results use text encoding and ByteString results use binary encoding.

Traced String

Name to use with traced, or "" for no tracing. By default traces using the name of the executable.

Timeout Double

Abort the computation after N seconds, will raise a failure exit code. Calls interruptProcessGroupOf and terminateProcess, but may sometimes fail to abort the process and not timeout.

WithStdout Bool

Should I include the stdout in the exception if the command fails? Defaults to False.

WithStderr Bool

Should I include the stderr in the exception if the command fails? Defaults to True.

EchoStdout Bool

Should I echo the stdout? Defaults to True unless a Stdout result is required or you use FileStdout.

EchoStderr Bool

Should I echo the stderr? Defaults to True unless a Stderr result is required or you use FileStderr.

FileStdout FilePath

Should I put the stdout to a file.

FileStderr FilePath

Should I put the stderr to a file.

AutoDeps

Compute dependencies automatically. Only works if shakeLintInside has been set to the files where autodeps might live.

UserCommand String

The command the user thinks about, before any munging. Defaults to the actual command.

FSAOptions String

Options to fsatrace, a list of strings with characters such as "r" (reads) "w" (writes). Defaults to "rwmdqt" if the output of fsatrace is required.

CloseFileHandles

Before starting the command in the child process, close all file handles except stdin, stdout, stderr in the child process. Uses close_fds from package process and comes with the same caveats, i.e. runtime is linear with the maximum number of open file handles (RLIMIT_NOFILE, see man 2 getrlimit on Linux).

NoProcessGroup

Don't run the process in its own group. Required when running docker. Will mean that process timeouts and asyncronous exceptions may not properly clean up child processes.

InheritStdin

Cause the stdin from the parent to be inherited. Might also require NoProcessGroup on Linux. Ignored if you explicitly pass a stdin.

Instances

Eq CmdOption

Defined in Development.Shake.Internal.CmdOption

Methods

(==) :: CmdOption -> CmdOption -> Bool

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

Data CmdOption

Defined in Development.Shake.Internal.CmdOption

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> CmdOption -> c CmdOption

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c CmdOption

toConstr :: CmdOption -> Constr

dataTypeOf :: CmdOption -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c CmdOption)

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c CmdOption)

gmapT :: (forall b. Data b => b -> b) -> CmdOption -> CmdOption

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> CmdOption -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> CmdOption -> r

gmapQ :: (forall d. Data d => d -> u) -> CmdOption -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> CmdOption -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> CmdOption -> m CmdOption

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> CmdOption -> m CmdOption

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> CmdOption -> m CmdOption

Ord CmdOption

Defined in Development.Shake.Internal.CmdOption

Methods

compare :: CmdOption -> CmdOption -> Ordering

(<) :: CmdOption -> CmdOption -> Bool

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

(>) :: CmdOption -> CmdOption -> Bool

(>=) :: CmdOption -> CmdOption -> Bool

max :: CmdOption -> CmdOption -> CmdOption

min :: CmdOption -> CmdOption -> CmdOption

Show CmdOption

Defined in Development.Shake.Internal.CmdOption

Methods

showsPrec :: Int -> CmdOption -> ShowS

show :: CmdOption -> String

showList :: [CmdOption] -> ShowS

IsCmdArgument CmdOption

Defined in Development.Shake.Command

Methods

toCmdArgument :: CmdOption -> CmdArgument

IsCmdArgument [CmdOption]

Defined in Development.Shake.Command

Methods

toCmdArgument :: [CmdOption] -> CmdArgument

addPath :: MonadIO m => [String] -> [String] -> m CmdOption

Deprecated: Use AddPath. This function will be removed in a future version.

Add a prefix and suffix to the $PATH environment variable. For example:

opt <- addPath ["/usr/special"] []
cmd opt "userbinary --version"

Would prepend /usr/special to the current $PATH, and the command would pick /usr/special/userbinary, if it exists. To add other variables see addEnv.

addEnv :: MonadIO m => [(String, String)] -> m CmdOption

Deprecated: Use AddEnv. This function will be removed in a future version.

Add a single variable to the environment. For example:

opt <- addEnv [("CFLAGS","-O2")]
cmd opt "gcc -c main.c"

Would add the environment variable $CFLAGS with value -O2. If the variable $CFLAGS was already defined it would be overwritten. If you wish to modify $PATH see addPath.