8.14 Using Guix Interactively

The guix repl command gives you access to a warm and friendly read-eval-print loop (REPL) (veja Invocando guix repl). If you’re getting into Guix programming—defining your own packages, writing manifests, defining services for Guix System or Guix Home, etc.—you will surely find it convenient to toy with ideas at the REPL.

If you use Emacs, the most convenient way to do that is with Geiser (veja A configuração perfeita), but you do not have to use Emacs to enjoy the REPL. When using guix repl or guile in the terminal, we recommend using Readline for completion and Colorized to get colorful output. To do that, you can run:

guix install guile guile-readline guile-colorized

... and then create a .guile file in your home directory containing this:

(use-modules (ice-9 readline) (ice-9 colorized))

(activate-readline)
(activate-colorized)

The REPL lets you evaluate Scheme code; you type a Scheme expression at the prompt, and the REPL prints what it evaluates to:

$ guix repl
scheme@(guix-user)> (+ 2 3)
$1 = 5
scheme@(guix-user)> (string-append "a" "b")
$2 = "ab"

It becomes interesting when you start fiddling with Guix at the REPL. The first thing you’ll want to do is to “import” the (guix) module, which gives access to the main part of the programming interface, and perhaps a bunch of useful Guix modules. You could type (use-modules (guix)), which is valid Scheme code to import a module (veja Using Guile Modules em GNU Guile Reference Manual), but the REPL provides the use command as a shorthand notation (veja REPL Commands em GNU Guile Reference Manual):

scheme@(guix-user)> ,use (guix)
scheme@(guix-user)> ,use (gnu packages base)

Notice that REPL commands are introduced by a leading comma. A REPL command like use is not valid Scheme code; it’s interpreted specially by the REPL.

Guix extends the Guile REPL with additional commands for convenience. Among those, the build command comes in handy: it ensures that the given file-like object is built, building it if needed, and returns its output file name(s). In the example below, we build the coreutils and grep packages, as well as a “computed file” (veja computed-file), and we use the scandir procedure to list the files in Grep’s /bin directory:

scheme@(guix-user)> ,build coreutils
$1 = "/gnu/store/…-coreutils-8.32-debug"
$2 = "/gnu/store/…-coreutils-8.32"
scheme@(guix-user)> ,build grep
$3 = "/gnu/store/…-grep-3.6"
scheme@(guix-user)> ,build (computed-file "x" #~(mkdir #$output))
building /gnu/store/…-x.drv...
$4 = "/gnu/store/…-x"
scheme@(guix-user)> ,use(ice-9 ftw)
scheme@(guix-user)> (scandir (string-append $3 "/bin"))
$5 = ("." ".." "egrep" "fgrep" "grep")

As a packager, you may be willing to inspect the build phases or flags of a given package; this is particularly useful when relying a lot on inheritance to define package variants (veja Definindo variantes de pacote) or when package arguments are a result of some computation, both of which can make it harder to foresee what ends up in the package arguments. Additional commands let you inspect those package arguments:

scheme@(guix-user)> ,phases grep
$1 = (modify-phases %standard-phases
       (add-after 'install 'fix-egrep-and-fgrep
         (lambda* (#:key outputs #:allow-other-keys)
           (let* ((out (assoc-ref outputs "out"))
                  (bin (string-append out "/bin")))
             (substitute* (list (string-append bin "/egrep")
                                (string-append bin "/fgrep"))
               (("^exec grep")
                (string-append "exec " bin "/grep")))))))
scheme@(guix-user)> ,configure-flags findutils
$2 = (list "--localstatedir=/var")
scheme@(guix-user)> ,make-flags binutils
$3 = '("MAKEINFO=true")

At a lower-level, a useful command is lower: it takes a file-like object and “lowers” it into a derivation (veja Derivações) or a store file:

scheme@(guix-user)> ,lower grep
$6 = #<derivation /gnu/store/…-grep-3.6.drv => /gnu/store/…-grep-3.6 7f0e639115f0>
scheme@(guix-user)> ,lower (plain-file "x" "Hello!")
$7 = "/gnu/store/…-x"

The full list of REPL commands can be seen by typing ,help guix and is given below for reference.

REPL command: build object

Lower object and build it if it’s not already built, returning its output file name(s).

REPL command: lower object

Lower object into a derivation or store file name and return it.

REPL command: verbosity level

Change build verbosity to level.

This is similar to the --verbosity command-line option (veja Opções de compilação comum): level 0 means total silence, level 1 shows build events only, and higher levels print build logs.

REPL command: phases package

REPL command: configure-flags package

REPL command: make-flags package

These REPL commands return the value of one element of the arguments field of package (veja package Reference): the first one show the staged code associated with #:phases (veja Fases de construção), the second shows the code for #:configure-flags, and ,make-flags returns the code for #:make-flags.

REPL command: run-in-store exp

Run exp, a monadic expression, through the store monad. Veja A mônada do armazém, for more information.

REPL command: enter-store-monad

Enter a new REPL to evaluate monadic expressions (veja A mônada do armazém). You can quit this “inner” REPL by typing ,q.