Safe Haskell	Safe-Inferred
Language	Haskell2010

Development.Shake.Command

Description

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.

Synopsis

command :: (Partial, CmdResult r) => [CmdOption] -> String -> [String] -> Action r
command_ :: Partial => [CmdOption] -> String -> [String] -> Action ()
cmd :: (Partial, CmdArguments args) => args :-> Action r
cmd_ :: (Partial, CmdArguments args, Unit args) => args :-> Action ()
unit :: m () -> m ()
newtype CmdArgument = CmdArgument [Either CmdOption String]
class CmdArguments t where
- cmdArguments :: Partial => CmdArgument -> t
class IsCmdArgument a where
- toCmdArgument :: a -> CmdArgument
type (:->) a t = a
newtype Stdout a = Stdout {
- fromStdout :: a
}
newtype StdoutTrim a = StdoutTrim {
- fromStdoutTrim :: a
}
newtype Stderr a = Stderr {
- fromStderr :: a
}
newtype Stdouterr a = Stdouterr {
- fromStdouterr :: a
}
newtype Exit = Exit {
- fromExit :: ExitCode
}
newtype Process = Process {
- fromProcess :: ProcessHandle
}
newtype CmdTime = CmdTime {
- fromCmdTime :: Double
}
newtype CmdLine = CmdLine {
- fromCmdLine :: String
}
data FSATrace a
- = FSAWrite a
- | FSARead a
- | FSADelete a
- | FSAMove a a
- | FSAQuery a
- | FSATouch a
class CmdResult a
class CmdString a
data CmdOption
- = Cwd FilePath
- | Env [(String, String)]
- | AddEnv String String
- | RemEnv String
- | AddPath [String] [String]
- | Stdin String
- | StdinBS ByteString
- | FileStdin FilePath
- | Shell
- | BinaryPipes
- | Traced String
- | Timeout Double
- | WithStdout Bool
- | WithStderr Bool
- | EchoStdout Bool
- | EchoStderr Bool
- | FileStdout FilePath
- | FileStderr FilePath
- | AutoDeps
- | UserCommand String
- | FSAOptions String
- | CloseFileHandles
- | NoProcessGroup
- | InheritStdin
addPath :: MonadIO m => [String] -> [String] -> m CmdOption
addEnv :: MonadIO m => [(String, String)] -> m CmdOption

Documentation

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

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

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 Source #

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

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 Source #

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

Constructors

CmdArgument [Either CmdOption String]

Instances

Instances details

Monoid CmdArgument Source #

Instance details