diff --git a/src/System/Process/Read.hs b/src/System/Process/Read.hs index 0f1fbdc795..af82d82b31 100644 --- a/src/System/Process/Read.hs +++ b/src/System/Process/Read.hs @@ -142,6 +142,8 @@ envHelper :: EnvOverride -> Maybe [(String, String)] envHelper = Just . eoStringList -- | Read from the process, ignoring any output. +-- +-- Throws a 'ReadProcessException' exception if the process fails. readProcessNull :: (MonadIO m, MonadLogger m, MonadBaseControl IO m, MonadCatch m) => Maybe (Path Abs Dir) -- ^ Optional working directory -> EnvOverride @@ -215,6 +217,8 @@ instance Exception ReadProcessException -- If the process fails, spits out stdout and stderr as error log -- level. Should not be used for long-running processes or ones with -- lots of output; for that use 'sinkProcessStdoutLogStderr'. +-- +-- Throws a 'ReadProcessException' if unsuccessful. sinkProcessStdout :: (MonadIO m, MonadLogger m, MonadBaseControl IO m, MonadCatch m) => Maybe (Path Abs Dir) -- ^ Optional directory to run in @@ -258,6 +262,8 @@ logProcessStderrStdout mdir name menv args = liftBaseWith $ \restore -> do void $ restore $ sinkProcessStderrStdout mdir menv name args logLines logLines -- | Consume the stdout and stderr of a process feeding strict 'S.ByteString's to the consumers. +-- +-- Throws a 'ReadProcessException' if unsuccessful in launching, or 'ProcessExitedUnsuccessfully' if the process itself fails. sinkProcessStderrStdout :: forall m e o. (MonadIO m, MonadLogger m) => Maybe (Path Abs Dir) -- ^ Optional directory to run in -> EnvOverride @@ -277,6 +283,8 @@ sinkProcessStderrStdout wd menv name args sinkStderr sinkStdout = do f err out = (err $$ sinkStderr) `concurrently` (out $$ sinkStdout) -- | Like sinkProcessStderrStdout, but receives Handles for stderr and stdout instead of 'Sink's. +-- +-- Throws a 'ReadProcessException' if unsuccessful in launching, or 'ProcessExitedUnsuccessfully' if the process itself fails. sinkProcessStderrStdoutHandle :: (MonadIO m, MonadLogger m) => Maybe (Path Abs Dir) -- ^ Optional directory to run in -> EnvOverride @@ -299,6 +307,8 @@ sinkProcessStderrStdoutHandle wd menv name args err out = do -- | Perform pre-call-process tasks. Ensure the working directory exists and find the -- executable path. +-- +-- Throws a 'ReadProcessException' if unsuccessful. preProcess :: (MonadIO m) => Maybe (Path Abs Dir) -- ^ Optional directory to create if necessary -> EnvOverride -- ^ How to override environment diff --git a/src/System/Process/Run.hs b/src/System/Process/Run.hs index da55223427..1148a4083b 100644 --- a/src/System/Process/Run.hs +++ b/src/System/Process/Run.hs @@ -85,7 +85,7 @@ runCmd' modCP cmd@(Cmd{..}) mbErrMsg = do -- | Like 'System.Process.callProcess', but takes an optional working directory and -- environment override, and throws 'ProcessExitedUnsuccessfully' if the --- process exits unsuccessfully. +-- process exits unsuccessfully and a 'ReadProcessException' if the executable is not found. -- -- Inherits stdout and stderr. callProcess :: (MonadIO m, MonadLogger m) => Cmd -> m () @@ -93,7 +93,7 @@ callProcess = callProcess' id -- | Like 'System.Process.callProcess', but takes an optional working directory and -- environment override, and throws 'ProcessExitedUnsuccessfully' if the --- process exits unsuccessfully. +-- process exits unsuccessfully and a 'ReadProcessException' if the executable is not found. -- -- Inherits stdout and stderr. callProcess' :: (MonadIO m, MonadLogger m) @@ -140,6 +140,7 @@ createProcess' tag modCP cmd = do $logCreateProcess c liftIO $ System.Process.createProcess_ tag c +-- Throws a 'ReadProcessException' if process is not found. cmdToCreateProcess :: MonadIO m => Cmd -> m CreateProcess cmdToCreateProcess (Cmd wd cmd0 menv args) = do cmd <- preProcess wd menv cmd0