aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2022-01-25 23:29:40 +0100
committerLudovic Courtès <ludo@gnu.org>2022-01-25 23:54:44 +0100
commit5543f80df75be94b5f9e1511a07c6feab6f59ba1 (patch)
tree6be0c6729100c948332eaedcf13c771e6aab8b3d
parentd582b399781f6fd80c63d07746524196603972e4 (diff)
downloadguix-5543f80df75be94b5f9e1511a07c6feab6f59ba1.tar
guix-5543f80df75be94b5f9e1511a07c6feab6f59ba1.tar.gz
doc: Document 'invoke' & co.
* doc/guix.texi (Build Utilities)[Program Invocation]: New subsection.
-rw-r--r--doc/guix.texi74
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