diff options
| -rw-r--r-- | doc/guix.texi | 74 |
1 files changed, 74 insertions, 0 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 6e3a780ccb..62e994ceb1 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -9338,6 +9338,80 @@ in a build phase of the @code{wireguard-tools} package: `("PATH" ":" prefix ,(list coreutils)))))) @end lisp +@subsection Program Invocation + +@cindex program invocation, from Scheme +@cindex invoking programs, from Scheme +You'll find handy procedures to spawn processes in this module, +essentially convenient wrappers around Guile's @code{system*} +(@pxref{Processes, @code{system*},, guile, GNU Guile Reference Manual}). + +@deffn {Scheme Procedure} invoke @var{program} @var{args}@dots{} +Invoke @var{program} with the given @var{args}. Raise an +@code{&invoke-error} exception if the exit code is non-zero; otherwise +return @code{#t}. + +The advantage compared to @code{system*} is that you do not need to +check the return value. This reduces boilerplate in shell-script-like +snippets for instance in package build phases. +@end deffn + +@deffn {Scheme Procedure} invoke-error? @var{c} +Return true if @var{c} is an @code{&invoke-error} condition. +@end deffn + +@deffn {Scheme Procedure} invoke-error-program @var{c} +@deffnx {Scheme Procedure} invoke-error-arguments @var{c} +@deffnx {Scheme Procedure} invoke-error-exit-status @var{c} +@deffnx {Scheme Procedure} invoke-error-term-signal @var{c} +@deffnx {Scheme Procedure} invoke-error-stop-signal @var{c} +Access specific fields of @var{c}, an @code{&invoke-error} condition. +@end deffn + +@deffn {Scheme Procedure} report-invoke-error @var{c} [@var{port}] +Report to @var{port} (by default the current error port) about @var{c}, +an @code{&invoke-error} condition, in a human-friendly way. + +Typical usage would look like this: + +@lisp +(use-modules (srfi srfi-34) ;for 'guard' + (guix build utils)) + +(guard (c ((invoke-error? c) + (report-invoke-error c))) + (invoke "date" "--imaginary-option")) + +@print{} command "date" "--imaginary-option" failed with status 1 +@end lisp +@end deffn + +@deffn {Scheme Procedure} invoke/quiet @var{program} @var{args}@dots{} +Invoke @var{program} with @var{args} and capture @var{program}'s +standard output and standard error. If @var{program} succeeds, print +nothing and return the unspecified value; otherwise, raise a +@code{&message} error condition that includes the status code and the +output of @var{program}. + +Here's an example: + +@lisp +(use-modules (srfi srfi-34) ;for 'guard' + (srfi srfi-35) ;for 'message-condition?' + (guix build utils)) + +(guard (c ((message-condition? c) + (display (condition-message c)))) + (invoke/quiet "date") ;all is fine + (invoke/quiet "date" "--imaginary-option")) + +@print{} 'date --imaginary-option' exited with status 1; output follows: + + date: unrecognized option '--imaginary-option' + Try 'date --help' for more information. +@end lisp +@end deffn + @subsection Build Phases @cindex build phases |