Development.Shake.Command

Deprecated: This module should no longer be imported as all the functions are available directly from Development.Shake. In future versions this module will be removed.

Documentation

command :: CmdResult r => [CmdOption] -> String -> [String] -> Action r

Execute a system command. Before running command make sure you need any files that are required 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_.

command_ :: [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 :: CmdArguments args => args :-> Action r

A variable arity version of command.

• String arguments are treated as whitespace separated arguments.
• [String] arguments are treated as literal arguments.
• CmdOption arguments are used as options.

To take the examples from command:

 () <- 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

When passing file arguments we use [myfile] so that if the myfile variable contains spaces they are properly escaped.

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, bind the result to (), or include a type signature.

newtype Stdout

Collect the stdout of the process. If you are collecting the stdout, it will not be echoed to the terminal, unless you include EchoStdout.

Constructors

Stdout

Fields

fromStdout :: String

Instances

CmdResult Stdout

newtype Stderr

Collect the stderr of the process. If you are collecting the stderr, it will not be echoed to the terminal, unless you include EchoStderr.

Constructors

Stderr

Fields

fromStderr :: String

Instances

CmdResult Stderr

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

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.

Instances

CmdResult ()

CmdResult ExitCode

CmdResult Exit

CmdResult Stderr

CmdResult Stdout

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

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

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.

Env [(String, String)]

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

Stdin String

Given as the stdin of the spawned process. By default no stdin is given.

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 streams use text encoding.

Traced String

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

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.

EchoStderr Bool

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

Instances

Eq CmdOption

Ord CmdOption

Show CmdOption