The procedures that operate on the store described in the previous sections all take an open connection to the build daemon as their first argument. Although the underlying model is functional, they either have side effects or depend on the current state of the store.
The former is inconvenient: the connection to the build daemon has to be carried around in all those functions, making it impossible to compose functions that do not take that parameter with functions that do. The latter can be problematic: since store operations have side effects and/or depend on external state, they have to be properly sequenced.
This is where the
(guix monads) module comes in. This module
provides a framework for working with monads, and a particularly
useful monad for our uses, the store monad. Monads are a
construct that allows two things: associating “context” with values
(in our case, the context is the store), and building sequences of
computations (here computations includes accesses to the store.) Values
in a monad—values that carry this additional context—are called
monadic values; procedures that return such values are called
Consider this “normal” procedure:
(define (sh-symlink store) ;; Return a derivation that symlinks the 'bash' executable. (let* ((drv (package-derivation store bash)) (out (derivation->output-path drv)) (sh (string-append out "/bin/bash"))) (build-expression->derivation store "sh" `(symlink ,sh %output))))
(guix monads), it may be rewritten as a monadic function:
(define (sh-symlink) ;; Same, but return a monadic value. (gexp->derivation "sh" #~(symlink (string-append #$bash "/bin/bash") #$output)))
There are two things to note in the second version: the
parameter is now implicit, and the monadic value returned by
package-file—a wrapper around
derivation->output-path—is bound using
instead of plain
Calling the monadic
profile.sh has no effect. To get the desired
effect, one must use
(run-with-store (open-connection) (profile.sh)) ⇒ /gnu/store/...-profile.sh
Note that the
(guix monad-repl) module extends Guile’s REPL with
new “meta-commands” to make it easier to deal with monadic procedures:
enter-store-monad. The former, is used
to “run” a single monadic value through the store:
scheme@(guile-user)> ,run-in-store (package->derivation hello) $1 = #<derivation /gnu/store/…-hello-2.9.drv => …>
The latter enters a recursive REPL, where all the return values are automatically run through the store:
scheme@(guile-user)> ,enter-store-monad store-monad@(guile-user) > (package->derivation hello) $2 = #<derivation /gnu/store/…-hello-2.9.drv => …> store-monad@(guile-user) > (text-file "foo" "Hello!") $3 = "/gnu/store/…-foo" store-monad@(guile-user) > ,q scheme@(guile-user)>
Note that non-monadic values cannot be returned in the
The main syntactic forms to deal with monads in general are described below.
return forms in body as being
Return a monadic value that encapsulates val.
Bind monadic value mval, passing its “contents” to monadic procedure mproc4.
Bind the variables var to the monadic values mval in
body. The form (var -> val) binds var to the
“normal” value val, as per
mlet* is to
let* is to
(see Local Bindings in GNU Guile Reference Manual).
Bind mexp and the following monadic expressions in sequence, returning the result of the last expression.
This is akin to
mlet, except that the return values of the
monadic expressions are ignored. In that sense, it is analogous to
begin, but applied to monadic expressions.
The interface to the store monad provided by
(guix monads) is as
The store monad. Values in the store monad encapsulate accesses to the
store. When its effect is needed, a value of the store monad must be
“evaluated” by passing it to the
run-with-store procedure (see
Run mval, a monadic value in the store monad, in store, an open store connection.
Return as a monadic value the absolute file name in the store of the file containing text, a string.
Return as a monadic value a derivation that builds a text file containing all of text. text may list, in addition to strings, packages, derivations, and store file names; the resulting store file holds references to all these.
This variant should be preferred over
text-file anytime the file
to create will reference items from the store. This is typically the
case when building a configuration file that embeds store file names,
(define (profile.sh) ;; Return the name of a shell script in the store that ;; initializes the 'PATH' environment variable. (text-file* "profile.sh" "export PATH=" coreutils "/bin:" grep "/bin:" sed "/bin\n"))
In this example, the resulting /gnu/store/…-profile.sh file will references coreutils, grep, and sed, thereby preventing them from being garbage-collected during its lifetime.
Return the name of file once interned in the store. Use name as its store name, or the basename of file if name is omitted.
When recursive? is true, the contents of file are added recursively; if file designates a flat file and recursive? is true, its contents are added, and its permission bits are kept.
The example below adds a file to the store, under two different names:
(run-with-store (open-connection) (mlet %store-monad ((a (interned-file "README")) (b (interned-file "README" "LEGU-MIN"))) (return (list a b)))) ⇒ ("/gnu/store/rwm…-README" "/gnu/store/44i…-LEGU-MIN")
value in the absolute file name of file within the output directory of package. When file is omitted, return the name of the output directory of package. When target is true, use it as a cross-compilation target triplet.
Monadic version of
package-cross-derivation (see Defining Packages).
This operation is commonly referred to as “bind”, but that name denotes an unrelated procedure in Guile. Thus we use this somewhat cryptic symbol inherited from the Haskell language.