This is guix.info, produced by makeinfo version 6.8 from guix.texi.

Copyright © 2012–2025 Ludovic Courtès
Copyright © 2013, 2014, 2016, 2024 Andreas Enge
Copyright © 2013 Nikita Karetnikov
Copyright © 2014, 2015, 2016 Alex Kost
Copyright © 2015, 2016 Mathieu Lirzin
Copyright © 2014 Pierre-Antoine Rault
Copyright © 2015 Taylan Ulrich Bayırlı/Kammer
Copyright © 2015, 2016, 2017, 2019, 2020, 2021, 2023, 2025 Leo Famulari
Copyright © 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023 Ricardo
Wurmus
Copyright © 2016 Ben Woodcroft
Copyright © 2016, 2017, 2018, 2021 Chris Marusich
Copyright © 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2025 Efraim
Flashner
Copyright © 2016 John Darrington
Copyright © 2016, 2017 Nikita Gillmann
Copyright © 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025
Janneke Nieuwenhuizen
Copyright © 2016, 2017, 2018, 2019, 2020, 2021 Julien Lepiller
Copyright © 2016 Alex ter Weele
Copyright © 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines
Copyright © 2017, 2018, 2019 Clément Lassieur
Copyright © 2017, 2018, 2020, 2021, 2022 Mathieu Othacehe
Copyright © 2017 Federico Beffa
Copyright © 2017, 2018, 2024, 2025 Carlo Zancanaro
Copyright © 2017 Thomas Danckaert
Copyright © 2017 humanitiesNerd
Copyright © 2017, 2021 Christine Lemmer-Webber
Copyright © 2017, 2018, 2019, 2020, 2021, 2022 Marius Bakke
Copyright © 2017, 2019, 2020, 2022 Hartmut Goebel
Copyright © 2017, 2019–2025 Maxim Cournoyer
Copyright © 2017–2022 Tobias Geerinckx-Rice
Copyright © 2017 George Clemmer
Copyright © 2017 Andy Wingo
Copyright © 2017, 2018, 2019, 2020, 2023, 2024, 2025 Arun Isaac
Copyright © 2017 nee
Copyright © 2018 Rutger Helling
Copyright © 2018, 2021, 2023, 2025 Oleg Pykhalov
Copyright © 2018 Mike Gerwitz
Copyright © 2018 Pierre-Antoine Rouby
Copyright © 2018, 2019 Gábor Boskovits
Copyright © 2018, 2019, 2020, 2022, 2023, 2024 Florian Pelz
Copyright © 2018 Laura Lazzati
Copyright © 2018 Alex Vong
Copyright © 2019 Josh Holland
Copyright © 2019, 2020 Diego Nicola Barbato
Copyright © 2019 Ivan Petkov
Copyright © 2019 Jakob L. Kreuze
Copyright © 2019 Kyle Andrews
Copyright © 2019 Alex Griffin
Copyright © 2019, 2020, 2021, 2022 Guillaume Le Vaillant
Copyright © 2020 Liliana Marie Prikler
Copyright © 2019, 2020, 2021, 2022, 2023 Simon Tournier
Copyright © 2020 Wiktor Żelazny
Copyright © 2020 Damien Cassou
Copyright © 2020 Jakub Kądziołka
Copyright © 2020 Jack Hill
Copyright © 2020 Naga Malleswari
Copyright © 2020, 2021 Brice Waegeneire
Copyright © 2020 R Veera Kumar
Copyright © 2020, 2021, 2022 Pierre Langlois
Copyright © 2020 pinoaffe
Copyright © 2020, 2023 André Batista
Copyright © 2020, 2021 Alexandru-Sergiu Marton
Copyright © 2020 raingloom
Copyright © 2020 Daniel Brooks
Copyright © 2020 John Soo
Copyright © 2020 Jonathan Brielmaier
Copyright © 2020 Edgar Vincent
Copyright © 2021, 2022 Maxime Devos
Copyright © 2021 B. Wilson
Copyright © 2021 Xinglu Chen
Copyright © 2021 Raghav Gururajan
Copyright © 2021 Domagoj Stolfa
Copyright © 2021 Hui Lu
Copyright © 2021 pukkamustard
Copyright © 2021 Alice Brenon
Copyright © 2021-2023 Josselin Poiret
Copyright © 2021, 2023 muradm
Copyright © 2021, 2022 Andrew Tropin
Copyright © 2021 Sarah Morgensen
Copyright © 2022 Remco van ’t Veer
Copyright © 2022 Aleksandr Vityazev
Copyright © 2022 Philip M^{c}Grath
Copyright © 2022 Karl Hallsby
Copyright © 2022 Justin Veilleux
Copyright © 2022 Reily Siegel
Copyright © 2022 Simon Streit
Copyright © 2022 (
Copyright © 2022 John Kehayias
Copyright © 2022⁠–⁠2023 Bruno Victal
Copyright © 2022 Ivan Vilata-i-Balaguer
Copyright © 2023-2025 Giacomo Leidi
Copyright © 2022 Antero Mejr
Copyright © 2023 Karl Hallsby
Copyright © 2023 Nathaniel Nicandro
Copyright © 2023 Tanguy Le Carrour
Copyright © 2023-2024 Zheng Junjie
Copyright © 2023 Brian Cully
Copyright © 2023 Felix Lechner
Copyright © 2023 Foundation Devices, Inc.
Copyright © 2023 Thomas Ieong
Copyright © 2023 Saku Laesvuori
Copyright © 2023 Graham James Addis
Copyright © 2023-2025 Tomas Volf
Copyright © 2024, 2025 Herman Rimm
Copyright © 2024 Matthew Trzcinski
Copyright © 2024 Richard Sent
Copyright © 2024 Dariqq
Copyright © 2024 Denis ’GNUtoo’ Carikli
Copyright © 2024 Fabio Natali
Copyright © 2024 Arnaud Daby-Seesaram
Copyright © 2024-2025 Nigko Yerden
Copyright © 2024 Troy Figiel
Copyright © 2024 Sharlatan Hellseher
Copyright © 2024 45mg
Copyright © 2024 Greg Hogan
Copyright © 2025 Sören Tempel
Copyright © 2025 Rostislav Svoboda
Copyright © 2025 Zacchaeus
Copyright © 2025 Sergio Pastor Pérez
Copyright © 2024 Evgeny Pisemsky
Copyright © 2025 jgart
Copyright © 2025 Artur Wroblewski
Copyright © 2025 Edouard Klein
Copyright © 2025 Rodion Goritskov
Copyright © 2025 dan
Copyright © 2025 Noé Lopez

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled “GNU Free
Documentation License”.
INFO-DIR-SECTION System administration
START-INFO-DIR-ENTRY
* Guix: (guix).       Manage installed software and system configuration.
* guix package: (guix)Invoking guix package.  Installing, removing, and upgrading packages.
* guix gc: (guix)Invoking guix gc.            Reclaiming unused disk space.
* guix pull: (guix)Invoking guix pull.        Update the list of available packages.
* guix system: (guix)Invoking guix system.    Manage the operating system configuration.
* guix deploy: (guix)Invoking guix deploy.    Manage operating system configurations for remote hosts.
END-INFO-DIR-ENTRY

INFO-DIR-SECTION Software development
START-INFO-DIR-ENTRY
* guix shell: (guix)Invoking guix shell.      Creating software environments.
* guix environment: (guix)Invoking guix environment.  Building development environments with Guix.
* guix build: (guix)Invoking guix build.      Building packages.
* guix pack: (guix)Invoking guix pack.        Creating binary bundles.
END-INFO-DIR-ENTRY


File: guix.info,  Node: Programming Interface,  Next: Utilities,  Prev: Development,  Up: Top

8 Programming Interface
***********************

GNU Guix provides several Scheme programming interfaces (APIs) to
define, build, and query packages.  The first interface allows users to
write high-level package definitions.  These definitions refer to
familiar packaging concepts, such as the name and version of a package,
its build system, and its dependencies.  These definitions can then be
turned into concrete build actions.

   Build actions are performed by the Guix daemon, on behalf of users.
In a standard setup, the daemon has write access to the store—the
‘/gnu/store’ directory—whereas users do not.  The recommended setup also
has the daemon perform builds in chroots, under specific build users, to
minimize interference with the rest of the system.

   Lower-level APIs are available to interact with the daemon and the
store.  To instruct the daemon to perform a build action, users actually
provide it with a “derivation”.  A derivation is a low-level
representation of the build actions to be taken, and the environment in
which they should occur—derivations are to package definitions what
assembly is to C programs.  The term “derivation” comes from the fact
that build results _derive_ from them.

   This chapter describes all these APIs in turn, starting from
high-level package definitions.  *Note Source Tree Structure::, for a
more general overview of the source code.

* Menu:

* Package Modules::             Packages from the programmer’s viewpoint.
* Defining Packages::           Defining new packages.
* Defining Package Variants::   Customizing packages.
* Writing Manifests::           The bill of materials of your environment.
* Build Systems::               Specifying how packages are built.
* Build Phases::                Phases of the build process of a package.
* Build Utilities::             Helpers for your package definitions and more.
* Search Paths::                Declaring search path environment variables.
* The Store::                   Manipulating the package store.
* Derivations::                 Low-level interface to package derivations.
* The Store Monad::             Purely functional interface to the store.
* G-Expressions::               Manipulating build expressions.
* Invoking guix repl::          Programming Guix in Guile
* Using Guix Interactively::    Fine-grain interaction at the REPL.


File: guix.info,  Node: Package Modules,  Next: Defining Packages,  Up: Programming Interface

8.1 Package Modules
===================

From a programming viewpoint, the package definitions of the GNU
distribution are provided by Guile modules in the ‘(gnu packages ...)’
name space(1) (*note Guile modules: (guile)Modules.).  For instance, the
‘(gnu packages emacs)’ module exports a variable named ‘emacs’, which is
bound to a ‘<package>’ object (*note Defining Packages::).

   The ‘(gnu packages ...)’ module name space is automatically scanned
for packages by the command-line tools.  For instance, when running
‘guix install emacs’, all the ‘(gnu packages ...)’ modules are scanned
until one that exports a package object whose name is ‘emacs’ is found.
This package search facility is implemented in the ‘(gnu packages)’
module.

   Users can store package definitions in modules with different
names—e.g., ‘(my-packages emacs)’(2).  There are two ways to make these
package definitions visible to the user interfaces:

  1. By adding the directory containing your package modules to the
     search path with the ‘-L’ flag of ‘guix package’ and other commands
     (*note Common Build Options::), or by setting the
     ‘GUIX_PACKAGE_PATH’ environment variable described below.

  2. By defining a “channel” and configuring ‘guix pull’ so that it
     pulls from it.  A channel is essentially a Git repository
     containing package modules.  *Note Channels::, for more information
     on how to define and use channels.

   ‘GUIX_PACKAGE_PATH’ works similarly to other search path variables:

 -- Environment Variable: GUIX_PACKAGE_PATH
     This is a colon-separated list of directories to search for
     additional package modules.  Directories listed in this variable
     take precedence over the own modules of the distribution.

   The distribution is fully “bootstrapped” and “self-contained”: each
package is built based solely on other packages in the distribution.
The root of this dependency graph is a small set of “bootstrap
binaries”, provided by the ‘(gnu packages bootstrap)’ module.  For more
information on bootstrapping, *note Bootstrapping::.

   ---------- Footnotes ----------

   (1) Note that packages under the ‘(gnu packages ...)’ module name
space are not necessarily “GNU packages”.  This module naming scheme
follows the usual Guile module naming convention: ‘gnu’ means that these
modules are distributed as part of the GNU system, and ‘packages’
identifies modules that define packages.

   (2) Note that the file name and module name must match.  For
instance, the ‘(my-packages emacs)’ module must be stored in a
‘my-packages/emacs.scm’ file relative to the load path specified with
‘--load-path’ or ‘GUIX_PACKAGE_PATH’.  *Note (guile)Modules and the File
System::, for details.


File: guix.info,  Node: Defining Packages,  Next: Defining Package Variants,  Prev: Package Modules,  Up: Programming Interface

8.2 Defining Packages
=====================

The high-level interface to package definitions is implemented in the
‘(guix packages)’ and ‘(guix build-system)’ modules.  As an example, the
package definition, or “recipe”, for the GNU Hello package looks like
this:

     (define-module (gnu packages hello)
       #:use-module (guix packages)
       #:use-module (guix download)
       #:use-module (guix build-system gnu)
       #:use-module (guix licenses)
       #:use-module (gnu packages gawk))

     (define-public hello
       (package
         (name "hello")
         (version "2.10")
         (source (origin
                   (method url-fetch)
                   (uri (string-append "mirror://gnu/hello/hello-" version
                                       ".tar.gz"))
                   (sha256
                    (base32
                     "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
         (build-system gnu-build-system)
         (arguments
          (list #:configure-flags #~(list "--enable-silent-rules")))
         (inputs (list gawk))
         (synopsis "Hello, GNU world: An example GNU package")
         (description "Guess what GNU Hello prints!")
         (home-page "https://www.gnu.org/software/hello/")
         (license gpl3+)))

Without being a Scheme expert, the reader may have guessed the meaning
of the various fields here.  This expression binds the variable ‘hello’
to a ‘<package>’ record (*note Scheme records: (guile)SRFI-9.).  This
package object can be inspected using procedures found in the ‘(guix
packages)’ module; for instance, ‘(package-name hello)’
returns—surprise!—‘"hello"’.

     Quick start: Impatient?  With luck, you may be able to import part
     or all of the definition of the package you are interested in from
     another repository, using the ‘guix import’ command (*note Invoking
     guix import::).

     Alternatively, try out the Guix-Packager interface
     (https://guix-hpc.gitlabpages.inria.fr/guix-packager/) in your web
     browser to produce a preliminary package definition.

   In the example above, ‘hello’ is defined in a module of its own,
‘(gnu packages hello)’.  Technically, this is not strictly necessary,
but it is convenient to do so: all the packages defined in modules under
‘(gnu packages ...)’ are automatically known to the command-line tools
(*note Package Modules::).

   There are a few points worth noting in the above package definition:

   • The ‘source’ field of the package is an ‘<origin>’ object (*note
     origin Reference::, for the complete reference).  Here, the
     ‘url-fetch’ method from ‘(guix download)’ is used, meaning that the
     source is a file to be downloaded over FTP or HTTP.

     The ‘mirror://gnu’ prefix instructs ‘url-fetch’ to use one of the
     GNU mirrors defined in ‘(guix download)’.

     The ‘sha256’ field specifies the expected SHA256 hash of the file
     being downloaded.  It is mandatory, and allows Guix to check the
     integrity of the file.  The ‘(base32 ...)’ form introduces the
     base32 representation of the hash.  You can obtain this information
     with ‘guix download’ (*note Invoking guix download::) and ‘guix
     hash’ (*note Invoking guix hash::).

     When needed, the ‘origin’ form can also have a ‘patches’ field
     listing patches to be applied, and a ‘snippet’ field giving a
     Scheme expression to modify the source code.

   • The ‘build-system’ field specifies the procedure to build the
     package (*note Build Systems::).  Here, ‘gnu-build-system’
     represents the familiar GNU Build System, where packages may be
     configured, built, and installed with the usual ‘./configure &&
     make && make check && make install’ command sequence.

     When you start packaging non-trivial software, you may need tools
     to manipulate those build phases, manipulate files, and so on.
     *Note Build Utilities::, for more on this.

   • The ‘arguments’ field specifies options for the build system (*note
     Build Systems::).  Here it is interpreted by ‘gnu-build-system’ as
     a request run ‘configure’ with the ‘--enable-silent-rules’ flag.

     The value of the ‘arguments’ field is a list of arguments passed to
     the build system and that end up being applied, as with ‘apply’
     (*note ‘apply’: (guile)Fly Evaluation.).

     The hash-colon (‘#:’) sequence defines a Scheme “keyword” (*note
     (guile)Keywords::), and ‘#:configure-flags’ is a keyword used to
     pass a keyword argument to the build system (*note (guile)Coding
     With Keywords::).

     What about these hash-tilde (‘#~’) characters?  This is
     Guix-specific syntax introducing a so-called “G-expression” (*note
     G-Expressions::), which denotes code that is “staged” for eventual
     evaluation: this staged code is only evaluated if and when
     attempting to build the package, by the build daemon.  In this
     example, the staged code is the ‘(list ...)’ expression, which
     builds a list of one element, the configure flag.

   • The ‘inputs’ field specifies inputs to the build process—i.e.,
     build-time or run-time dependencies of the package.  Here, we add
     an input, a reference to the ‘gawk’ variable; ‘gawk’ is itself
     bound to a ‘<package>’ object.

     Note that GCC, Coreutils, Bash, and other essential tools do not
     need to be specified as inputs here.  Instead, ‘gnu-build-system’
     takes care of ensuring that they are present (*note Build
     Systems::).

     However, any other dependencies need to be specified in the
     ‘inputs’ field.  Any dependency not specified here will simply be
     unavailable to the build process, possibly leading to a build
     failure.

   *Note package Reference::, for a full description of possible fields.

     Going further: Intimidated by the Scheme language or curious about
     it?  The Cookbook has a short section to get started that recaps
     some of the things shown above and explains the fundamentals.
     *Note (guix-cookbook)A Scheme Crash Course::, for more information.

   Once a package definition is in place, the package may actually be
built using the ‘guix build’ command-line tool (*note Invoking guix
build::), troubleshooting any build failures you encounter (*note
Debugging Build Failures::).  You can easily jump back to the package
definition using the ‘guix edit’ command (*note Invoking guix edit::).
*Note Packaging Guidelines::, for more information on how to test
package definitions, and *note Invoking guix lint::, for information on
how to check a definition for style conformance.  Lastly, *note
Channels::, for information on how to extend the distribution by adding
your own package definitions in a “channel”.

   Finally, updating the package definition to a new upstream version
can be partly automated by the ‘guix refresh’ command (*note Invoking
guix refresh::).

   Behind the scenes, a derivation corresponding to the ‘<package>’
object is first computed by the ‘package-derivation’ procedure.  That
derivation is stored in a ‘.drv’ file under ‘/gnu/store’.  The build
actions it prescribes may then be realized by using the
‘build-derivations’ procedure (*note The Store::).

 -- Procedure: package-derivation store package [system]
     Return the ‘<derivation>’ object of PACKAGE for SYSTEM (*note
     Derivations::).

     PACKAGE must be a valid ‘<package>’ object, and SYSTEM must be a
     string denoting the target system type—e.g., ‘"x86_64-linux"’ for
     an x86_64 Linux-based GNU system.  STORE must be a connection to
     the daemon, which operates on the store (*note The Store::).

Similarly, it is possible to compute a derivation that cross-builds a
package for some other system:

 -- Procedure: package-cross-derivation store package target [system]
     Return the ‘<derivation>’ object of PACKAGE cross-built from SYSTEM
     to TARGET.

     TARGET must be a valid GNU triplet denoting the target hardware and
     operating system, such as ‘"aarch64-linux-gnu"’ (*note
     (autoconf)Specifying Target Triplets::).

   Once you have package definitions, you can easily define _variants_
of those packages.  *Note Defining Package Variants::, for more on that.

* Menu:

* package Reference::           The package data type.
* origin Reference::            The origin data type.


File: guix.info,  Node: package Reference,  Next: origin Reference,  Up: Defining Packages

8.2.1 ‘package’ Reference
-------------------------

This section summarizes all the options available in ‘package’
declarations (*note Defining Packages::).

 -- Data Type: package
     This is the data type representing a package recipe.

     ‘name’
          The name of the package, as a string.

     ‘version’
          The version of the package, as a string.  *Note Version
          Numbers::, for guidelines.

     ‘source’
          An object telling how the source code for the package should
          be acquired.  Most of the time, this is an ‘origin’ object,
          which denotes a file fetched from the Internet (*note origin
          Reference::).  It can also be any other “file-like” object
          such as a ‘local-file’, which denotes a file from the local
          file system (*note ‘local-file’: G-Expressions.).

     ‘build-system’
          The build system that should be used to build the package
          (*note Build Systems::).

     ‘arguments’ (default: ‘'()’)
          The arguments that should be passed to the build system (*note
          Build Systems::).  This is a list, typically containing
          sequential keyword-value pairs, as in this example:

               (package
                 (name "example")
                 ;; several fields omitted
                 (arguments
                   (list #:tests? #f                     ;skip tests
                         #:make-flags #~'("VERBOSE=1")   ;pass flags to 'make'
                         #:configure-flags #~'("--enable-frobbing"))))

          The exact set of supported keywords depends on the build
          system (*note Build Systems::), but you will find that almost
          all of them honor ‘#:configure-flags’, ‘#:make-flags’,
          ‘#:tests?’, and ‘#:phases’.  The ‘#:phases’ keyword in
          particular lets you modify the set of build phases for your
          package (*note Build Phases::).

          The REPL has dedicated commands to interactively inspect
          values of some of these arguments, as a convenient debugging
          aid (*note Using Guix Interactively::).

               Compatibility Note: Until version 1.3.0, the ‘arguments’
               field would typically use ‘quote’ (‘'’) or ‘quasiquote’
               (‘`’) and no G-expressions, like so:

                    (package
                      ;; several fields omitted
                      (arguments   ;old-style quoted arguments
                       '(#:tests? #f
                         #:configure-flags '("--enable-frobbing"))))

               To convert from that style to the one shown above, you
               can run ‘guix style -S arguments PACKAGE’ (*note Invoking
               guix style::).

     ‘inputs’ (default: ‘'()’)
     ‘native-inputs’ (default: ‘'()’)
     ‘propagated-inputs’ (default: ‘'()’)
          These fields list dependencies of the package.  Each element
          of these lists is either a package, origin, or other
          “file-like object” (*note G-Expressions::); to specify the
          output of that file-like object that should be used, pass a
          two-element list where the second element is the output (*note
          Packages with Multiple Outputs::, for more on package
          outputs).  For example, the list below specifies three inputs:

               (list libffi libunistring
                     `(,glib "bin"))      ;the "bin" output of GLib

          In the example above, the ‘"out"’ output of ‘libffi’ and
          ‘libunistring’ is used.

               Compatibility Note: Until version 1.3.0, input lists were
               a list of tuples, where each tuple has a label for the
               input (a string) as its first element, a package, origin,
               or derivation as its second element, and optionally the
               name of the output thereof that should be used, which
               defaults to ‘"out"’.  For example, the list below is
               equivalent to the one above, but using the “old input
               style”:

                    ;; Old input style (deprecated).
                    `(("libffi" ,libffi)
                      ("libunistring" ,libunistring)
                      ("glib:bin" ,glib "bin"))  ;the "bin" output of GLib

               This style is now deprecated; it is still supported but
               support will be removed in a future version.  It should
               not be used for new package definitions.  *Note Invoking
               guix style::, on how to migrate to the new style.

          The distinction between ‘native-inputs’ and ‘inputs’ is
          necessary when considering cross-compilation.  When
          cross-compiling, dependencies listed in ‘inputs’ are built for
          the _target_ architecture; conversely, dependencies listed in
          ‘native-inputs’ are built for the architecture of the _build_
          machine.

          ‘native-inputs’ is typically used to list tools needed at
          build time, but not at run time, such as Autoconf, Automake,
          pkg-config, Gettext, or Bison.  ‘guix lint’ can report likely
          mistakes in this area (*note Invoking guix lint::).

          Lastly, ‘propagated-inputs’ is similar to ‘inputs’, but the
          specified packages will be automatically installed to profiles
          (*note the role of profiles in Guix: Features.) alongside the
          package they belong to (*note ‘guix package’:
          package-cmd-propagated-inputs, for information on how ‘guix
          package’ deals with propagated inputs).

          For example this is necessary when packaging a C/C++ library
          that needs headers of another library to compile, or when a
          pkg-config file refers to another one via its ‘Requires’
          field.

          Another example where ‘propagated-inputs’ is useful is for
          languages that lack a facility to record the run-time search
          path akin to the ‘RUNPATH’ of ELF files; this includes Guile,
          Python, Perl, and more.  When packaging libraries written in
          those languages, ensure they can find library code they depend
          on at run time by listing run-time dependencies in
          ‘propagated-inputs’ rather than ‘inputs’.

     ‘outputs’ (default: ‘'("out")’)
          The list of output names of the package.  *Note Packages with
          Multiple Outputs::, for typical uses of additional outputs.

     ‘native-search-paths’ (default: ‘'()’)
     ‘search-paths’ (default: ‘'()’)
          A list of ‘search-path-specification’ objects describing
          search-path environment variables honored by the package.
          *Note Search Paths::, for more on search path specifications.

          As for inputs, the distinction between ‘native-search-paths’
          and ‘search-paths’ only matters when cross-compiling.  In a
          cross-compilation context, ‘native-search-paths’ applies
          exclusively to native inputs whereas ‘search-paths’ applies
          only to host inputs.

          Packages such as cross-compilers care about target inputs—for
          instance, our (modified) GCC cross-compiler has
          ‘CROSS_C_INCLUDE_PATH’ in ‘search-paths’, which allows it to
          pick ‘.h’ files for the target system and _not_ those of
          native inputs.  For the majority of packages though, only
          ‘native-search-paths’ makes sense.

     ‘replacement’ (default: ‘#f’)
          This must be either ‘#f’ or a package object that will be used
          as a “replacement” for this package.  *Note grafts: Security
          Updates, for details.

     ‘synopsis’
          A one-line description of the package.

     ‘description’
          A more elaborate description of the package, as a string in
          Texinfo syntax.

     ‘license’
          The license of the package; a value from ‘(guix licenses)’, or
          a list of such values.

     ‘home-page’
          The URL to the home-page of the package, as a string.

     ‘supported-systems’ (default: ‘%supported-systems’)
          The list of systems supported by the package, as strings of
          the form ‘architecture-kernel’, for example ‘"x86_64-linux"’.

     ‘location’ (default: source location of the ‘package’ form)
          The source location of the package.  It is useful to override
          this when inheriting from another package, in which case this
          field is not automatically corrected.

 -- Macro: this-package
     When used in the _lexical scope_ of a package field definition,
     this identifier resolves to the package being defined.

     The example below shows how to add a package as a native input of
     itself when cross-compiling:

          (package
            (name "guile")
            ;; ...

            ;; When cross-compiled, Guile, for example, depends on
            ;; a native version of itself.  Add it here.
            (native-inputs (if (%current-target-system)
                               (list this-package)
                               '())))

     It is an error to refer to ‘this-package’ outside a package
     definition.

   The following helper procedures are provided to help deal with
package inputs.

 -- Procedure: lookup-package-input package name
 -- Procedure: lookup-package-native-input package name
 -- Procedure: lookup-package-propagated-input package name
 -- Procedure: lookup-package-direct-input package name
     Look up NAME among PACKAGE’s inputs (or native, propagated, or
     direct inputs).  Return it if found, ‘#f’ otherwise.

     NAME is the name of a package or the file name of an origin
     depended on.  Here’s how you might use it:

          (use-modules (guix packages) (gnu packages base))

          (lookup-package-direct-input coreutils "gmp")
          ⇒ #<package gmp@6.2.1 ...>

     In this example we obtain the ‘gmp’ package that is among the
     direct inputs of ‘coreutils’.

     When looking up an origin, use the name that appears in the
     origin’s ‘file-name’ field or its default file name—e.g.,
     ‘"foo-1.2.tar.gz"’.

   Sometimes you will want to obtain the list of inputs needed to
_develop_ a package—all the inputs that are visible when the package is
compiled.  This is what the ‘package-development-inputs’ procedure
returns.

 -- Procedure: package-development-inputs package [system] [#:target #f]
     Return the list of inputs required by PACKAGE for development
     purposes on SYSTEM.  When TARGET is true, return the inputs needed
     to cross-compile PACKAGE from SYSTEM to TARGET, where TARGET is a
     triplet such as ‘"aarch64-linux-gnu"’.

     Note that the result includes both explicit inputs and implicit
     inputs—inputs automatically added by the build system (*note Build
     Systems::).  Let us take the ‘hello’ package to illustrate that:

          (use-modules (gnu packages base) (guix packages))

          hello
          ⇒ #<package hello@2.10 gnu/packages/base.scm:79 7f585d4f6790>

          (package-direct-inputs hello)
          ⇒ ()

          (package-development-inputs hello)
          ⇒ (("source" ...) ("tar" #<package tar@1.32 ...>) ...)

     In this example, ‘package-direct-inputs’ returns the empty list,
     because ‘hello’ has zero explicit dependencies.  Conversely,
     ‘package-development-inputs’ includes inputs implicitly added by
     ‘gnu-build-system’ that are required to build ‘hello’: tar, gzip,
     GCC, libc, Bash, and more.  To visualize it, ‘guix graph hello’
     would show you explicit inputs, whereas ‘guix graph -t bag hello’
     would include implicit inputs (*note Invoking guix graph::).

   Because packages are regular Scheme objects that capture a complete
dependency graph and associated build procedures, it is often useful to
write procedures that take a package and return a modified version
thereof according to some parameters.  Below are a few examples.

 -- Procedure: package-with-c-toolchain package toolchain
     Return a variant of PACKAGE that uses TOOLCHAIN instead of the
     default GNU C/C++ toolchain.  TOOLCHAIN must be a list of inputs
     (label/package tuples) providing equivalent functionality, such as
     the ‘gcc-toolchain’ package.

     The example below returns a variant of the ‘hello’ package built
     with GCC 10.x and the rest of the GNU tool chain (Binutils and the
     GNU C Library) instead of the default tool chain:

          (let ((toolchain (specification->package "gcc-toolchain@10")))
            (package-with-c-toolchain hello `(("toolchain" ,toolchain))))

     The build tool chain is part of the “implicit inputs” of
     packages—it’s usually not listed as part of the various “inputs”
     fields and is instead pulled in by the build system.  Consequently,
     this procedure works by changing the build system of PACKAGE so
     that it pulls in TOOLCHAIN instead of the defaults.  *Note Build
     Systems::, for more on build systems.


File: guix.info,  Node: origin Reference,  Prev: package Reference,  Up: Defining Packages

8.2.2 ‘origin’ Reference
------------------------

This section documents “origins”.  An ‘origin’ declaration specifies
data that must be “produced”—downloaded, usually—and whose content hash
is known in advance.  Origins are primarily used to represent the source
code of packages (*note Defining Packages::).  For that reason, the
‘origin’ form allows you to declare patches to apply to the original
source code as well as code snippets to modify it.

 -- Data Type: origin
     This is the data type representing a source code origin.

     ‘uri’
          An object containing the URI of the source.  The object type
          depends on the ‘method’ (see below).  For example, when using
          the URL-FETCH method of ‘(guix download)’, the valid ‘uri’
          values are: a URL represented as a string, or a list thereof.

     ‘method’
          A monadic procedure that handles the given URI.  The procedure
          must accept at least three arguments: the value of the ‘uri’
          field and the hash algorithm and hash value specified by the
          ‘hash’ field.  It must return a store item or a derivation in
          the store monad (*note The Store Monad::); most methods return
          a fixed-output derivation (*note Derivations::).

          Commonly used methods include ‘url-fetch’, which fetches data
          from a URL, and ‘git-fetch’, which fetches data from a Git
          repository (see below).

     ‘sha256’
          A bytevector containing the SHA-256 hash of the source.  This
          is equivalent to providing a ‘content-hash’ SHA256 object in
          the ‘hash’ field described below.

     ‘hash’
          The ‘content-hash’ object of the source—see below for how to
          use ‘content-hash’.

          You can obtain this information using ‘guix download’ (*note
          Invoking guix download::) or ‘guix hash’ (*note Invoking guix
          hash::).

     ‘file-name’ (default: ‘#f’)
          The file name under which the source code should be saved.
          When this is ‘#f’, a sensible default value will be used in
          most cases.  In case the source is fetched from a URL, the
          file name from the URL will be used.  For version control
          checkouts, it is recommended to provide the file name
          explicitly because the default is not very descriptive.

     ‘patches’ (default: ‘'()’)
          A list of file names, origins, or file-like objects (*note
          file-like objects: G-Expressions.) pointing to patches to be
          applied to the source.

          This list of patches must be unconditional.  In particular, it
          cannot depend on the value of ‘%current-system’ or
          ‘%current-target-system’.

     ‘snippet’ (default: ‘#f’)
          A G-expression (*note G-Expressions::) or S-expression that
          will be run in the source directory.  This is a convenient way
          to modify the source, sometimes more convenient than a patch.

     ‘patch-flags’ (default: ‘'("-p1")’)
          A list of command-line flags that should be passed to the
          ‘patch’ command.

     ‘patch-inputs’ (default: ‘#f’)
          Input packages or derivations to the patching process.  When
          this is ‘#f’, the usual set of inputs necessary for patching
          are provided, such as GNU Patch.

     ‘modules’ (default: ‘'()’)
          A list of Guile modules that should be loaded during the
          patching process and while running the code in the ‘snippet’
          field.

     ‘patch-guile’ (default: ‘#f’)
          The Guile package that should be used in the patching process.
          When this is ‘#f’, a sensible default is used.

 -- Data Type: content-hash VALUE [ALGORITHM]
     Construct a content hash object for the given ALGORITHM, and with
     VALUE as its hash value.  When ALGORITHM is omitted, assume it is
     ‘sha256’.

     VALUE can be a literal string, in which case it is base32-decoded,
     or it can be a bytevector.

     The following forms are all equivalent:

          (content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj")
          (content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"
                        sha256)
          (content-hash (base32
                         "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"))
          (content-hash (base64 "kkb+RPaP7uyMZmu4eXPVkM4BN8yhRd8BTHLslb6f/Rc=")
                        sha256)

     Technically, ‘content-hash’ is currently implemented as a macro.
     It performs sanity checks at macro-expansion time, when possible,
     such as ensuring that VALUE has the right size for ALGORITHM.

   As we have seen above, how exactly the data an origin refers to is
retrieved is determined by its ‘method’ field.  The ‘(guix download)’
module provides the most common method, ‘url-fetch’, described below.

 -- Procedure: url-fetch url hash-algo hash [name] [#:executable? #f]
     Return a fixed-output derivation that fetches data from URL (a
     string, or a list of strings denoting alternate URLs), which is
     expected to have hash HASH of type HASH-ALGO (a symbol).  By
     default, the file name is the base name of URL; optionally, NAME
     can specify a different file name.  When EXECUTABLE? is true, make
     the downloaded file executable.

     When one of the URL starts with ‘mirror://’, then its host part is
     interpreted as the name of a mirror scheme, taken from
     ‘%mirror-file’.

     Alternatively, when URL starts with ‘file://’, return the
     corresponding file name in the store.

   Likewise, the ‘(guix git-download)’ module defines the ‘git-fetch’
origin method, which fetches data from a Git version control repository,
and the ‘git-reference’ data type to describe the repository and
revision to fetch.

 -- Procedure: git-fetch ref hash-algo hash [name]
     Return a fixed-output derivation that fetches REF, a
     ‘<git-reference>’ object.  The output is expected to have recursive
     hash HASH of type HASH-ALGO (a symbol).  Use NAME as the file name,
     or a generic name if ‘#f’.

 -- Procedure: git-fetch/lfs ref hash-algo hash [name]
     This is a variant of the ‘git-fetch’ procedure that supports the
     Git LFS (Large File Storage) extension.  This may be useful to pull
     some binary test data to run the test suite of a package, for
     example.

 -- Data Type: git-reference
     This data type represents a Git reference for ‘git-fetch’ to
     retrieve.

     ‘url’
          The URL of the Git repository to clone.

     ‘commit’
          This string denotes either the commit to fetch (a hexadecimal
          string), or the tag to fetch.  You can also use a “short”
          commit ID or a ‘git describe’ style identifier such as
          ‘v1.0.1-10-g58d7909c97’.

     ‘recursive?’ (default: ‘#f’)
          This Boolean indicates whether to recursively fetch Git
          sub-modules.

     The example below denotes the ‘v2.10’ tag of the GNU Hello
     repository:

          (git-reference
            (url "https://git.savannah.gnu.org/git/hello.git")
            (commit "v2.10"))

     This is equivalent to the reference below, which explicitly names
     the commit:

          (git-reference
            (url "https://git.savannah.gnu.org/git/hello.git")
            (commit "dc7dc56a00e48fe6f231a58f6537139fe2908fb9"))

   For Mercurial repositories, the module ‘(guix hg-download)’ defines
the ‘hg-fetch’ origin method and ‘hg-reference’ data type for support of
the Mercurial version control system.

 -- Procedure: hg-fetch ref hash-algo hash [name]
     Return a fixed-output derivation that fetches REF, a
     ‘<hg-reference>’ object.  The output is expected to have recursive
     hash HASH of type HASH-ALGO (a symbol).  Use NAME as the file name,
     or a generic name if ‘#f’.

 -- Data Type: hg-reference
     This data type represents a Mercurial reference for ‘hg-fetch’ to
     retrieve.

     ‘url’
          The URL of the Mercurial repository to clone.

     ‘changeset’
          This string denotes the changeset to fetch.

   For Subversion repositories, the module ‘(guix svn-download)’ defines
the ‘svn-fetch’ origin method and ‘svn-reference’ data type for support
of the Subversion version control system.

 -- Procedure: svn-fetch ref hash-algo hash [name]
     Return a fixed-output derivation that fetches REF, a
     ‘<svn-reference>’ object.  The output is expected to have recursive
     hash HASH of type HASH-ALGO (a symbol).  Use NAME as the file name,
     or a generic name if ‘#f’.

 -- Data Type: svn-reference
     This data type represents a Subversion reference for ‘svn-fetch’ to
     retrieve.

     ‘url’
          The URL of the Subversion repository to clone.

     ‘revision’
          This string denotes the revision to fetch specified as a
          number.

     ‘recursive?’ (default: ‘#f’)
          This Boolean indicates whether to recursively fetch Subversion
          “externals”.

     ‘user-name’ (default: ‘#f’)
          The name of an account that has read-access to the repository,
          if the repository isn’t public.

     ‘password’ (default: ‘#f’)
          Password to access the Subversion repository, if required.

   For Bazaar repositories, the module ‘(guix bzr-download)’ defines the
‘bzr-fetch’ origin method and ‘bzr-reference’ data type for support of
the Bazaar version control system.

 -- Procedure: bzr-fetch ref hash-algo hash [name]
     Return a fixed-output derivation that fetches REF, a
     ‘<bzr-reference>’ object.  The output is expected to have recursive
     hash HASH of type HASH-ALGO (a symbol).  Use NAME as the file name,
     or a generic name if ‘#f’.

 -- Data Type: bzr-reference
     This data type represents a Bazaar reference for ‘bzr-fetch’ to
     retrieve.

     ‘url’
          The URL of the Bazaar repository to clone.

     ‘revision’
          This string denotes revision to fetch specified as a number.

   For CVS repositories, the module ‘(guix cvs-download)’ defines the
‘cvs-fetch’ origin method and ‘cvs-reference’ data type for support of
the Concurrent Versions System (CVS).

 -- Procedure: cvs-fetch ref hash-algo hash [name]
     Return a fixed-output derivation that fetches REF, a
     ‘<cvs-reference>’ object.  The output is expected to have recursive
     hash HASH of type HASH-ALGO (a symbol).  Use NAME as the file name,
     or a generic name if ‘#f’.

 -- Data Type: cvs-reference
     This data type represents a CVS reference for ‘cvs-fetch’ to
     retrieve.

     ‘root-directory’
          The CVS root directory.

     ‘module’
          Module to fetch.

     ‘revision’
          Revision to fetch.

     The example below denotes a version of gnu-standards to fetch:

          (cvs-reference
            (root-directory ":pserver:anonymous@cvs.savannah.gnu.org:/sources/gnustandards")
            (module "gnustandards")
            (revision "2020-11-25"))


File: guix.info,  Node: Defining Package Variants,  Next: Writing Manifests,  Prev: Defining Packages,  Up: Programming Interface

8.3 Defining Package Variants
=============================

One of the nice things with Guix is that, given a package definition,
you can easily _derive_ variants of that package—for a different
upstream version, with different dependencies, different compilation
options, and so on.  Some of these custom packages can be defined
straight from the command line (*note Package Transformation Options::).
This section describes how to define package variants in code.  This can
be useful in “manifests” (*note Writing Manifests::) and in your own
package collection (*note Creating a Channel::), among others!

   As discussed earlier, packages are first-class objects in the Scheme
language.  The ‘(guix packages)’ module provides the ‘package’ construct
to define new package objects (*note package Reference::).  The easiest
way to define a package variant is using the ‘inherit’ keyword together
with ‘package’.  This allows you to inherit from a package definition
while overriding the fields you want.

   For example, given the ‘hello’ variable, which contains a definition
for the current version of GNU Hello, here’s how you would define a
variant for version 2.2 (released in 2006, it’s vintage!):

     (use-modules (gnu packages base))    ;for 'hello'

     (define hello-2.2
       (package
         (inherit hello)
         (version "2.2")
         (source (origin
                   (method url-fetch)
                   (uri (string-append "mirror://gnu/hello/hello-" version
                                       ".tar.gz"))
                   (sha256
                    (base32
                     "0lappv4slgb5spyqbh6yl5r013zv72yqg2pcl30mginf3wdqd8k9"))))))

   The example above corresponds to what the ‘--with-version’ or
‘--with-source’ package transformations option do.  Essentially
‘hello-2.2’ preserves all the fields of ‘hello’, except ‘version’ and
‘source’, which it overrides.  Note that the original ‘hello’ variable
is still there, in the ‘(gnu packages base)’ module, unchanged.  When
you define a custom package like this, you are really _adding_ a new
package definition; the original one remains available.

   You can just as well define variants with a different set of
dependencies than the original package.  For example, the default ‘gdb’
package depends on ‘guile’, but since that is an optional dependency,
you can define a variant that removes that dependency like so:

     (use-modules (gnu packages gdb))   ;for 'gdb'

     (define gdb-sans-guile
       (package
         (inherit gdb)
         (inputs (modify-inputs (package-inputs gdb)
                   (delete "guile")))))

   The ‘modify-inputs’ form above removes the ‘"guile"’ package from the
‘inputs’ field of ‘gdb’.  The ‘modify-inputs’ macro is a helper that can
prove useful anytime you want to remove, add, or replace package inputs.

 -- Macro: modify-inputs inputs clauses
     Modify the given package inputs, as returned by ‘package-inputs’ &
     co., according to the given clauses.  Each clause must have one of
     the following forms:

     ‘(delete NAME...)’
          Delete from the inputs packages with the given NAMEs
          (strings).

     ‘(prepend PACKAGE...)’
          Add PACKAGEs to the front of the input list.

     ‘(append PACKAGE...)’
          Add PACKAGEs to the end of the input list.

     ‘(replace NAME REPLACEMENT)’
          Replace the package called NAME with REPLACEMENT.

     The example below removes the GMP and ACL inputs of Coreutils and
     adds libcap to the front of the input list:

          (modify-inputs (package-inputs coreutils)
            (delete "gmp" "acl")
            (prepend libcap))

     The example below replaces the ‘guile’ package from the inputs of
     ‘guile-redis’ with ‘guile-2.2’:

          (modify-inputs (package-inputs guile-redis)
            (replace "guile" guile-2.2))

     The last type of clause is ‘append’, to add inputs at the back of
     the list.

   In some cases, you may find it useful to write functions
(“procedures”, in Scheme parlance) that return a package based on some
parameters.  For example, consider the ‘luasocket’ library for the Lua
programming language.  We want to create ‘luasocket’ packages for major
versions of Lua.  One way to do that is to define a procedure that takes
a Lua package and returns a ‘luasocket’ package that depends on it:

     (define (make-lua-socket name lua)
       ;; Return a luasocket package built with LUA.
       (package
         (name name)
         (version "3.0")
         ;; several fields omitted
         (inputs (list lua))
         (synopsis "Socket library for Lua")))

     (define-public lua5.1-socket
       (make-lua-socket "lua5.1-socket" lua-5.1))

     (define-public lua5.2-socket
       (make-lua-socket "lua5.2-socket" lua-5.2))

   Here we have defined packages ‘lua5.1-socket’ and ‘lua5.2-socket’ by
calling ‘make-lua-socket’ with different arguments.  *Note
(guile)Procedures::, for more info on procedures.  Having top-level
public definitions for these two packages means that they can be
referred to from the command line (*note Package Modules::).

   These are pretty simple package variants.  As a convenience, the
‘(guix transformations)’ module provides a high-level interface that
directly maps to the more sophisticated package transformation options
(*note Package Transformation Options::):

 -- Procedure: options->transformation opts
     Return a procedure that, when passed an object to build (package,
     derivation, etc.), applies the transformations specified by OPTS
     and returns the resulting objects.  OPTS must be a list of
     symbol/string pairs such as:

          ((with-branch . "guile-gcrypt=master")
           (without-tests . "libgcrypt"))

     Each symbol names a transformation and the corresponding string is
     an argument to that transformation.

   For instance, a manifest equivalent to this command:

     guix build guix \
       --with-branch=guile-gcrypt=master \
       --with-debug-info=zlib

...  would look like this:

     (use-modules (guix transformations))

     (define transform
       ;; The package transformation procedure.
       (options->transformation
        '((with-branch . "guile-gcrypt=master")
          (with-debug-info . "zlib"))))

     (packages->manifest
      (list (transform (specification->package "guix"))))

   The ‘options->transformation’ procedure is convenient, but it’s
perhaps also not as flexible as you may like.  How is it implemented?
The astute reader probably noticed that most package transformation
options go beyond the superficial changes shown in the first examples of
this section: they involve “input rewriting”, whereby the dependency
graph of a package is rewritten by replacing specific inputs by others.

   Dependency graph rewriting, for the purposes of swapping packages in
the graph, is what the ‘package-input-rewriting’ procedure in ‘(guix
packages)’ implements.

 -- Procedure: package-input-rewriting replacements [rewrite-name]
          [#:deep? #t] [#:recursive? #f]
     Return a procedure that, when passed a package, replaces its direct
     and indirect dependencies, including implicit inputs when DEEP? is
     true, according to REPLACEMENTS.  REPLACEMENTS is a list of package
     pairs; the first element of each pair is the package to replace,
     and the second one is the replacement.

     When RECURSIVE? is true, apply replacements to the right-hand sides
     of REPLACEMENTS as well, recursively.

     Optionally, REWRITE-NAME is a one-argument procedure that takes the
     name of a package and returns its new name after rewrite.

Consider this example:

     (define libressl-instead-of-openssl
       ;; This is a procedure to replace OPENSSL by LIBRESSL,
       ;; recursively.
       (package-input-rewriting `((,openssl . ,libressl))))

     (define git-with-libressl
       (libressl-instead-of-openssl git))

Here we first define a rewriting procedure that replaces OPENSSL with
LIBRESSL.  Then we use it to define a “variant” of the GIT package that
uses LIBRESSL instead of OPENSSL.  This is exactly what the
‘--with-input’ command-line option does (*note ‘--with-input’: Package
Transformation Options.).

   The following variant of ‘package-input-rewriting’ can match packages
to be replaced by name rather than by identity.

 -- Procedure: package-input-rewriting/spec REPLACEMENTS [#:deep? #t]
          [#:replace-hidden? #t]
     Return a procedure that, given a package, applies the given
     REPLACEMENTS to all the package graph, including implicit inputs
     unless DEEP? is false.

     REPLACEMENTS is a list of spec/procedures pair; each spec is a
     package specification such as ‘"gcc"’ or ‘"guile@2"’, and each
     procedure takes a matching package and returns a replacement for
     that package.  Matching packages that have the ‘hidden?’ property
     set are not replaced unless REPLACE-HIDDEN? is set to true.

   The example above could be rewritten this way:

     (define libressl-instead-of-openssl
       ;; Replace all the packages called "openssl" with LibreSSL.
       (package-input-rewriting/spec `(("openssl" . ,(const libressl)))))

   The key difference here is that, this time, packages are matched by
spec and not by identity.  In other words, any package in the graph that
is called ‘openssl’ will be replaced.

   A more generic procedure to rewrite a package dependency graph is
‘package-mapping’: it supports arbitrary changes to nodes in the graph.

 -- Procedure: package-mapping proc [cut?] [#:deep? #f]
     Return a procedure that, given a package, applies PROC to all the
     packages depended on and returns the resulting package.  The
     procedure stops recursion when CUT? returns true for a given
     package.  When DEEP? is true, PROC is applied to implicit inputs as
     well.

     Tips: Understanding what a variant really looks like can be
     difficult as one starts combining the tools shown above.  There are
     several ways to inspect a package before attempting to build it
     that can prove handy:

        • You can inspect the package interactively at the REPL, for
          instance to view its inputs, the code of its build phases, or
          its configure flags (*note Using Guix Interactively::).

        • When rewriting dependencies, ‘guix graph’ can often help
          visualize the changes that are made (*note Invoking guix
          graph::).


File: guix.info,  Node: Writing Manifests,  Next: Build Systems,  Prev: Defining Package Variants,  Up: Programming Interface

8.4 Writing Manifests
=====================

‘guix’ commands let you specify package lists on the command line.  This
is convenient, but as the command line becomes longer and less trivial,
it quickly becomes more convenient to have that package list in what we
call a “manifest”.  A manifest is some sort of a “bill of materials”
that defines a package set.  You would typically come up with a code
snippet that builds the manifest, store it in a file, say
‘manifest.scm’, and then pass that file to the ‘-m’ (or ‘--manifest’)
option that many ‘guix’ commands support.  For example, here’s what a
manifest for a simple package set might look like:

     ;; Manifest for three packages.
     (specifications->manifest '("gcc-toolchain" "make" "git"))

   Once you have that manifest, you can pass it, for example, to ‘guix
package’ to install just those three packages to your profile (*note
‘-m’ option of ‘guix package’: profile-manifest.):

     guix package -m manifest.scm

...  or you can pass it to ‘guix shell’ (*note ‘-m’ option of ‘guix
shell’: shell-manifest.) to spawn an ephemeral environment:

     guix shell -m manifest.scm

...  or you can pass it to ‘guix pack’ in pretty much the same way
(*note ‘-m’ option of ‘guix pack’: pack-manifest.).  You can store the
manifest under version control, share it with others so they can easily
get set up, etc.

   But how do you write your first manifest?  To get started, maybe
you’ll want to write a manifest that mirrors what you already have in a
profile.  Rather than start from a blank page, ‘guix package’ can
generate a manifest for you (*note ‘guix package --export-manifest’:
export-manifest.):

     # Write to 'manifest.scm' a manifest corresponding to the
     # default profile, ~/.guix-profile.
     guix package --export-manifest > manifest.scm

   Or maybe you’ll want to “translate” command-line arguments into a
manifest.  In that case, ‘guix shell’ can help (*note ‘guix shell
--export-manifest’: shell-export-manifest.):

     # Write a manifest for the packages specified on the command line.
     guix shell --export-manifest gcc-toolchain make git > manifest.scm

   In both cases, the ‘--export-manifest’ option tries hard to generate
a faithful manifest; in particular, it takes package transformation
options into account (*note Package Transformation Options::).

     Note: Manifests are _symbolic_: they refer to packages of the
     channels _currently in use_ (*note Channels::).  In the example
     above, ‘gcc-toolchain’ might refer to version 14 today, but it
     might refer to version 16 two years from now.

     If you want to “pin” your software environment to specific package
     versions and variants, you need an additional piece of information:
     the list of channel revisions in use, as returned by ‘guix
     describe’.  *Note Replicating Guix::, for more information.

   Once you’ve obtained your first manifest, perhaps you’ll want to
customize it.  Since your manifest is code, you now have access to all
the Guix programming interfaces!

   Let’s assume you want a manifest to deploy a custom variant of GDB,
the GNU Debugger, that does not depend on Guile, together with another
package.  Building on the example seen in the previous section (*note
Defining Package Variants::), you can write a manifest along these
lines:

     (use-modules (guix packages)
                  (gnu packages gdb)               ;for 'gdb'
                  (gnu packages version-control))  ;for 'git'

     ;; Define a variant of GDB without a dependency on Guile.
     (define gdb-sans-guile
       (package
         (inherit gdb)
         (inputs (modify-inputs (package-inputs gdb)
                   (delete "guile")))))

     ;; Return a manifest containing that one package plus Git.
     (packages->manifest (list gdb-sans-guile git))

   Note that in this example, the manifest directly refers to the ‘gdb’
and ‘git’ variables, which are bound to a ‘package’ object (*note
package Reference::), instead of calling ‘specifications->manifest’ to
look up packages by name as we did before.  The ‘use-modules’ form at
the top lets us access the core package interface (*note Defining
Packages::) and the modules that define ‘gdb’ and ‘git’ (*note Package
Modules::).  Seamlessly, we’re weaving all this together—the
possibilities are endless, unleash your creativity!

   The data type for manifests as well as supporting procedures are
defined in the ‘(guix profiles)’ module, which is automatically
available to code passed to ‘-m’.  The reference follows.

 -- Data Type: manifest
     Data type representing a manifest.

     It currently has one field:

     ‘entries’
          This must be a list of ‘manifest-entry’ records—see below.

 -- Data Type: manifest-entry
     Data type representing a manifest entry.  A manifest entry contains
     essential metadata: a name and version string, the object (usually
     a package) for that entry, the desired output (*note Packages with
     Multiple Outputs::), and a number of optional pieces of information
     detailed below.

     Most of the time, you won’t build a manifest entry directly;
     instead, you will pass a package to ‘package->manifest-entry’,
     described below.  In some unusual cases though, you might want to
     create manifest entries for things that are _not_ packages, as in
     this example:

          ;; Manually build a single manifest entry for a non-package object.
          (let ((hello (program-file "hello" #~(display "Hi!"))))
            (manifest-entry
              (name "foo")
              (version "42")
              (item
               (computed-file "hello-directory"
                               #~(let ((bin (string-append #$output "/bin")))
                                   (mkdir #$output) (mkdir bin)
                                    (symlink #$hello
                                             (string-append bin "/hello")))))))

     The available fields are the following:

     ‘name’
     ‘version’
          Name and version string for this entry.

     ‘item’
          A package or other file-like object (*note file-like objects:
          G-Expressions.).

     ‘output’ (default: ‘"out"’)
          Output of ‘item’ to use, in case ‘item’ has multiple outputs
          (*note Packages with Multiple Outputs::).

     ‘dependencies’ (default: ‘'()’)
          List of manifest entries this entry depends on.  When building
          a profile, dependencies are added to the profile.

          Typically, the propagated inputs of a package (*note
          ‘propagated-inputs’: package Reference.) end up having a
          corresponding manifest entry in among the dependencies of the
          package’s own manifest entry.

     ‘search-paths’ (default: ‘'()’)
          The list of search path specifications honored by this entry
          (*note Search Paths::).

     ‘properties’ (default: ‘'()’)
          List of symbol/value pairs.  When building a profile, those
          properties get serialized.

          This can be used to piggyback additional metadata—e.g., the
          transformations applied to a package (*note Package
          Transformation Options::).

     ‘parent’ (default: ‘(delay #f)’)
          A promise pointing to the “parent” manifest entry.

          This is used as a hint to provide context when reporting an
          error related to a manifest entry coming from a ‘dependencies’
          field.

 -- Procedure: concatenate-manifests lst
     Concatenate the manifests listed in LST and return the resulting
     manifest.

 -- Procedure: package->manifest-entry package [output] [#:properties]
     Return a manifest entry for the OUTPUT of package PACKAGE, where
     OUTPUT defaults to ‘"out"’, and with the given PROPERTIES.  By
     default PROPERTIES is the empty list or, if one or more package
     transformations were applied to PACKAGE, it is an association list
     representing those transformations, suitable as an argument to
     ‘options->transformation’ (*note ‘options->transformation’:
     Defining Package Variants.).

     The code snippet below builds a manifest with an entry for the
     default output and the ‘send-email’ output of the ‘git’ package:

          (use-modules (gnu packages version-control))

          (manifest (list (package->manifest-entry git)
                          (package->manifest-entry git "send-email")))

 -- Procedure: packages->manifest packages
     Return a list of manifest entries, one for each item listed in
     PACKAGES.  Elements of PACKAGES can be either package objects or
     package/string tuples denoting a specific output of a package.

     Using this procedure, the manifest above may be rewritten more
     concisely:

          (use-modules (gnu packages version-control))

          (packages->manifest (list git `(,git "send-email")))

 -- Procedure: package->development-manifest package [system] [#:target]
     Return a manifest for the “development inputs” of PACKAGE for
     SYSTEM, optionally when cross-compiling to TARGET.  Development
     inputs include both explicit and implicit inputs of PACKAGE.

     Like the ‘-D’ option of ‘guix shell’ (*note ‘guix shell -D’:
     shell-development-option.), the resulting manifest describes the
     environment in which one can develop PACKAGE.  For example, suppose
     you’re willing to set up a development environment for Inkscape,
     with the addition of Git for version control; you can describe that
     “bill of materials” with the following manifest:

          (use-modules (gnu packages inkscape)          ;for 'inkscape'
                       (gnu packages version-control))  ;for 'git'

          (concatenate-manifests
           (list (package->development-manifest inkscape)
                 (packages->manifest (list git))))

     In this example, the development manifest that
     ‘package->development-manifest’ returns includes the compiler
     (GCC), the many supporting libraries (Boost, GLib, GTK, etc.), and
     a couple of additional development tools—these are the dependencies
     ‘guix show inkscape’ lists.

   Last, the ‘(gnu packages)’ module provides higher-level facilities to
build manifests.  In particular, it lets you look up packages by
name—see below.

 -- Procedure: specifications->manifest specs
     Given SPECS, a list of specifications such as ‘"emacs@25.2"’ or
     ‘"guile:debug"’, return a manifest.  Specs have the format that
     command-line tools such as ‘guix install’ and ‘guix package’
     understand (*note Invoking guix package::).

     As an example, it lets you rewrite the Git manifest that we saw
     earlier like this:

          (specifications->manifest '("git" "git:send-email"))

     Notice that we do not need to worry about ‘use-modules’, importing
     the right set of modules, and referring to the right variables.
     Instead, we directly refer to packages in the same way as on the
     command line, which can often be more convenient.


File: guix.info,  Node: Build Systems,  Next: Build Phases,  Prev: Writing Manifests,  Up: Programming Interface

8.5 Build Systems
=================

Each package definition specifies a “build system” and arguments for
that build system (*note Defining Packages::).  This ‘build-system’
field represents the build procedure of the package, as well as implicit
dependencies of that build procedure.

   Build systems are ‘<build-system>’ objects.  The interface to create
and manipulate them is provided by the ‘(guix build-system)’ module, and
actual build systems are exported by specific modules.

   Under the hood, build systems first compile package objects to
“bags”.  A “bag” is like a package, but with less ornamentation—in other
words, a bag is a lower-level representation of a package, which
includes all the inputs of that package, including some that were
implicitly added by the build system.  This intermediate representation
is then compiled to a derivation (*note Derivations::).  The
‘package-with-c-toolchain’ is an example of a way to change the implicit
inputs that a package’s build system pulls in (*note
‘package-with-c-toolchain’: package Reference.).

   Build systems accept an optional list of “arguments”.  In package
definitions, these are passed via the ‘arguments’ field (*note Defining
Packages::).  They are typically keyword arguments (*note keyword
arguments in Guile: (guile)Optional Arguments.).  The value of these
arguments is usually evaluated in the “build stratum”—i.e., by a Guile
process launched by the daemon (*note Derivations::).

   The main build system is ‘gnu-build-system’, which implements the
standard build procedure for GNU and many other packages.  It is
provided by the ‘(guix build-system gnu)’ module.

 -- Variable: gnu-build-system
     ‘gnu-build-system’ represents the GNU Build System, and variants
     thereof (*note configuration and makefile conventions:
     (standards)Configuration.).

     In a nutshell, packages using it are configured, built, and
     installed with the usual ‘./configure && make && make check && make
     install’ command sequence.  In practice, a few additional steps are
     often needed.  All these steps are split up in separate “phases”.
     *Note Build Phases::, for more info on build phases and ways to
     customize them.

     In addition, this build system ensures that the “standard”
     environment for GNU packages is available.  This includes tools
     such as GCC, libc, Coreutils, Bash, Make, Diffutils, grep, and sed
     (see the ‘(guix build-system gnu)’ module for a complete list).  We
     call these the “implicit inputs” of a package, because package
     definitions do not have to mention them.

     This build system supports a number of keyword arguments, which can
     be passed via the ‘arguments’ field of a package.  Here are some of
     the main parameters:

     ‘#:phases’
          This argument specifies build-side code that evaluates to an
          alist of build phases.  *Note Build Phases::, for more
          information.

     ‘#:configure-flags’
          This is a list of flags (strings) passed to the ‘configure’
          script.  *Note Defining Packages::, for an example.

     ‘#:make-flags’
          This list of strings contains flags passed as arguments to
          ‘make’ invocations in the ‘build’, ‘check’, and ‘install’
          phases.

     ‘#:out-of-source?’
          This Boolean, ‘#f’ by default, indicates whether to run builds
          in a build directory separate from the source tree.

          When it is true, the ‘configure’ phase creates a separate
          build directory, changes to that directory, and runs the
          ‘configure’ script from there.  This is useful for packages
          that require it, such as ‘glibc’.

     ‘#:tests?’
          This Boolean, ‘#t’ by default, indicates whether the ‘check’
          phase should run the package’s test suite.

     ‘#:test-target’
          This string, ‘"check"’ by default, gives the name of the
          makefile target used by the ‘check’ phase.

     ‘#:parallel-build?’
     ‘#:parallel-tests?’
          These Boolean values specify whether to build, respectively
          run the test suite, in parallel, with the ‘-j’ flag of ‘make’.
          When they are true, ‘make’ is passed ‘-jN’, where N is the
          number specified as the ‘--cores’ option of ‘guix-daemon’ or
          that of the ‘guix’ client command (*note ‘--cores’: Common
          Build Options.).

     ‘#:validate-runpath?’
          This Boolean, ‘#t’ by default, determines whether to
          “validate” the ‘RUNPATH’ of ELF binaries (‘.so’ shared
          libraries as well as executables) previously installed by the
          ‘install’ phase.  *Note the ‘validate-runpath’ phase:
          phase-validate-runpath, for details.

     ‘#:substitutable?’
          This Boolean, ‘#t’ by default, tells whether the package
          outputs should be substitutable—i.e., whether users should be
          able to obtain substitutes for them instead of building
          locally (*note Substitutes::).

     ‘#:allowed-references’
     ‘#:disallowed-references’
          When true, these arguments must be a list of dependencies that
          must not appear among the references of the build results.
          If, upon build completion, some of these references are
          retained, the build process fails.

          This is useful to ensure that a package does not erroneously
          keep a reference to some of it build-time inputs, in cases
          where doing so would, for example, unnecessarily increase its
          size (*note Invoking guix size::).

     Most other build systems support these keyword arguments.

   Other ‘<build-system>’ objects are defined to support other
conventions and tools used by free software packages.  They inherit most
of ‘gnu-build-system’, and differ mainly in the set of inputs implicitly
added to the build process, and in the list of phases executed.  Some of
these build systems are listed below.

 -- Variable: agda-build-system
     This variable is exported by ‘(guix build-system agda)’.  It
     implements a build procedure for Agda libraries.

     It adds ‘agda’ to the set of inputs.  A different Agda can be
     specified with the ‘#:agda’ key.

     The ‘#:plan’ key is a list of cons cells ‘(REGEXP . PARAMETERS)’,
     where REGEXP is a regexp that should match the ‘.agda’ files to
     build, and PARAMETERS is an optional list of parameters that will
     be passed to ‘agda’ when type-checking it.

     When the library uses Haskell to generate a file containing all
     imports, the convenience ‘#:gnu-and-haskell?’ can be set to ‘#t’ to
     add ‘ghc’ and the standard inputs of ‘gnu-build-system’ to the
     input list.  You will still need to manually add a phase or tweak
     the ‘'build’ phase, as in the definition of ‘agda-stdlib’.

 -- Variable: ant-build-system
     This variable is exported by ‘(guix build-system ant)’.  It
     implements the build procedure for Java packages that can be built
     with Ant build tool (https://ant.apache.org/).

     It adds both ‘ant’ and the “Java Development Kit” (JDK) as provided
     by the ‘icedtea’ package to the set of inputs.  Different packages
     can be specified with the ‘#:ant’ and ‘#:jdk’ parameters,
     respectively.

     When the original package does not provide a suitable Ant build
     file, the parameter ‘#:jar-name’ can be used to generate a minimal
     Ant build file ‘build.xml’ with tasks to build the specified jar
     archive.  In this case the parameter ‘#:source-dir’ can be used to
     specify the source sub-directory, defaulting to “src”.

     The ‘#:main-class’ parameter can be used with the minimal ant
     buildfile to specify the main class of the resulting jar.  This
     makes the jar file executable.  The ‘#:test-include’ parameter can
     be used to specify the list of junit tests to run.  It defaults to
     ‘(list "**/*Test.java")’.  The ‘#:test-exclude’ can be used to
     disable some tests.  It defaults to ‘(list "**/Abstract*.java")’,
     because abstract classes cannot be run as tests.

     The parameter ‘#:build-target’ can be used to specify the Ant task
     that should be run during the ‘build’ phase.  By default the “jar”
     task will be run.

 -- Variable: android-ndk-build-system
     This variable is exported by ‘(guix build-system android-ndk)’.  It
     implements a build procedure for Android NDK (native development
     kit) packages using a Guix-specific build process.

     The build system assumes that packages install their public
     interface (header) files to the subdirectory ‘include’ of the ‘out’
     output and their libraries to the subdirectory ‘lib’ the ‘out’
     output.

     It’s also assumed that the union of all the dependencies of a
     package has no conflicting files.

     For the time being, cross-compilation is not supported - so right
     now the libraries and header files are assumed to be host tools.

 -- Variable: asdf-build-system/source
 -- Variable: asdf-build-system/sbcl
 -- Variable: asdf-build-system/ecl
 -- Variable: asdf-build-system/clasp

     These variables, exported by ‘(guix build-system asdf)’, implement
     build procedures for Common Lisp packages using “ASDF”
     (https://common-lisp.net/project/asdf/).  ASDF is a system
     definition facility for Common Lisp programs and libraries.

     The ‘asdf-build-system/source’ system installs the packages in
     source form, and can be loaded using any common lisp
     implementation, via ASDF.  The others, such as
     ‘asdf-build-system/sbcl’, install binary systems in the format
     which a particular implementation understands.  These build systems
     can also be used to produce executable programs, or lisp images
     which contain a set of packages pre-loaded.

     The build system uses naming conventions.  For binary packages, the
     package name should be prefixed with the lisp implementation, such
     as ‘sbcl-’ for ‘asdf-build-system/sbcl’.

     Additionally, the corresponding source package should be labeled
     using the same convention as Python packages (*note Python
     Modules::), using the ‘cl-’ prefix.

     In order to create executable programs and images, the build-side
     procedures ‘build-program’ and ‘build-image’ can be used.  They
     should be called in a build phase after the
     ‘create-asdf-configuration’ phase, so that the system which was
     just built can be used within the resulting image.  ‘build-program’
     requires a list of Common Lisp expressions to be passed as the
     ‘#:entry-program’ argument.

     By default, all the ‘.asd’ files present in the sources are read to
     find system definitions.  The ‘#:asd-files’ parameter can be used
     to specify the list of ‘.asd’ files to read.  Furthermore, if the
     package defines a system for its tests in a separate file, it will
     be loaded before the tests are run if it is specified by the
     ‘#:test-asd-file’ parameter.  If it is not set, the files
     ‘<system>-tests.asd’, ‘<system>-test.asd’, ‘tests.asd’, and
     ‘test.asd’ will be tried if they exist.

     If for some reason the package must be named in a different way
     than the naming conventions suggest, or if several systems must be
     compiled, the ‘#:asd-systems’ parameter can be used to specify the
     list of system names.

 -- Variable: cargo-build-system
     This variable is exported by ‘(guix build-system cargo)’.  It
     supports builds of packages using Cargo, the build tool of the Rust
     programming language (https://www.rust-lang.org).

          Deprecation warning: Parameters ‘#:cargo-inputs’ and
          ‘#:cargo-development-inputs’, previously used for specifying
          source inputs, are deprecated.  Their support will be removed
          after Dec.  31, 2026.

     It adds ‘rust’ and ‘rust:cargo’ to the set of inputs.  A different
     Rust package can be specified with the ‘#:rust’ parameter.

     In its ‘unpack-rust-crates’, ‘configure’ and
     ‘patch-cargo-checksums’ phases, this build system will make any
     source inputs available to Cargo.  It will also remove an included
     ‘Cargo.lock’ file to be recreated by ‘cargo’ during the ‘build’
     phase.  The ‘package’ phase will run ‘cargo package’ to create a
     source crate for future use.  The ‘install’ phase installs the
     binaries defined by the crate.  Unless ‘install-source? #f’ is
     defined it will also install a source crate repository of itself
     and unpacked sources, to ease in future hacking on Rust packages.

     This build system supports Cargo workspaces
     (https://doc.rust-lang.org/cargo/reference/workspaces.html).
     Parameter ‘#:cargo-package-crates’ (default: ‘''()’) allows
     specifying names of library crates to package in the ‘package’
     phase.  Specified crates are packaged from left to right, in case
     there’s dependency among them.  For example, specifying
     ‘''("pcre2-sys" "pcre2")’ will package ‘"pcre2-sys"’ first and then
     ‘"pcre2"’.  Parameter ‘#:cargo-install-paths’ (default: ‘''()’)
     allows specifying paths of binary crates to install in the
     ‘install’ phase, ‘''("crates/atuin")’, for example.

     *Note Rust Crates::, for packaging guidelines.

 -- Variable: chicken-build-system
     This variable is exported by ‘(guix build-system chicken)’.  It
     builds CHICKEN Scheme (https://call-cc.org/) modules, also called
     “eggs” or “extensions”.  CHICKEN generates C source code, which
     then gets compiled by a C compiler, in this case GCC.

     This build system adds ‘chicken’ to the package inputs, as well as
     the packages of ‘gnu-build-system’.

     The build system can’t (yet) deduce the egg’s name automatically,
     so just like with ‘go-build-system’ and its ‘#:import-path’, you
     should define ‘#:egg-name’ in the package’s ‘arguments’ field.

     For example, if you are packaging the ‘srfi-1’ egg:

          (arguments '(#:egg-name "srfi-1"))

     Egg dependencies must be defined in ‘propagated-inputs’, not
     ‘inputs’ because CHICKEN doesn’t embed absolute references in
     compiled eggs.  Test dependencies should go to ‘native-inputs’, as
     usual.

 -- Variable: copy-build-system
     This variable is exported by ‘(guix build-system copy)’.  It
     supports builds of simple packages that don’t require much
     compiling, mostly just moving files around.

     It adds much of the ‘gnu-build-system’ packages to the set of
     inputs.  Because of this, the ‘copy-build-system’ does not require
     all the boilerplate code often needed for the
     ‘trivial-build-system’.

     To further simplify the file installation process, an
     ‘#:install-plan’ argument is exposed to let the packager specify
     which files go where.  The install plan is a list of ‘(SOURCE
     TARGET [FILTERS])’.  FILTERS are optional.

        • When SOURCE matches a file or directory without trailing
          slash, install it to TARGET.
             • If TARGET has a trailing slash, install SOURCE basename
               beneath TARGET.
             • Otherwise install SOURCE as TARGET.

        • When SOURCE is a directory with a trailing slash, or when
          FILTERS are used, the trailing slash of TARGET is implied with
          the same meaning as above.
             • Without FILTERS, install the full SOURCE _content_ to
               TARGET.
             • With FILTERS among ‘#:include’, ‘#:include-regexp’,
               ‘#:exclude’, ‘#:exclude-regexp’, only select files are
               installed depending on the filters.  Each filters is
               specified by a list of strings.
                  • With ‘#:include’, install all the files which the
                    path suffix matches at least one of the elements in
                    the given list.
                  • With ‘#:include-regexp’, install all the files which
                    the subpaths match at least one of the regular
                    expressions in the given list.
                  • The ‘#:exclude’ and ‘#:exclude-regexp’ filters are
                    the complement of their inclusion counterpart.
                    Without ‘#:include’ flags, install all files but
                    those matching the exclusion filters.  If both
                    inclusions and exclusions are specified, the
                    exclusions are done on top of the inclusions.
             • When a package has multiple outputs, the ‘#:output’
               argument can be used to specify which output label the
               files should be installed to.
          In all cases, the paths relative to SOURCE are preserved
          within TARGET.

     Examples:

        • ‘("foo/bar" "share/my-app/")’: Install ‘bar’ to
          ‘share/my-app/bar’.
        • ‘("foo/bar" "share/my-app/baz")’: Install ‘bar’ to
          ‘share/my-app/baz’.
        • ‘("foo/" "share/my-app")’: Install the content of ‘foo’ inside
          ‘share/my-app’, e.g., install ‘foo/sub/file’ to
          ‘share/my-app/sub/file’.
        • ‘("foo/" "share/my-app" #:include ("sub/file"))’: Install only
          ‘foo/sub/file’ to ‘share/my-app/sub/file’.
        • ‘("foo/sub" "share/my-app" #:include ("file"))’: Install
          ‘foo/sub/file’ to ‘share/my-app/file’.
        • ‘("foo/doc" "share/my-app/doc" #:output "doc")’: Install
          ‘"foo/doc"’ to ‘"share/my-app/doc"’ within the ‘"doc"’ output.

 -- Variable: vim-build-system
     This variable is exported by ‘(guix build-system vim)’.  It is an
     extension of the ‘copy-build-system’, installing Vim and Neovim
     plugins into locations where these two text editors know to find
     their plugins, using their packpaths.

     Packages which are prefixed with ‘vim-’ will be installed in Vim’s
     packpath, while those prefixed with ‘neovim-’ will be installed in
     Neovim’s packpath.  If there is a ‘doc’ directory with the plugin
     then helptags will be generated automatically.

     There are a couple of keywords added with the ‘vim-build-system’:
        • With ‘plugin-name’ it is possible to set the name of the
          plugin.  While by default this is set to the name and version
          of the package, it is often more helpful to set this to name
          which the upstream author calls their plugin.  This is the
          name used for ‘:packadd’ from inside Vim.
        • With ‘install-plan’ it is possible to augment the built-in
          install-plan of the ‘vim-build-system’.  This is particularly
          helpful if you have files which should be installed in other
          locations.  For more information about using the
          ‘install-plan’, see the ‘copy-build-system’ (*note
          ‘copy-build-system’: Build Systems.).
        • With ‘#:vim’ it is possible to add this package to Vim’s
          packpath, in addition to if it is added automatically because
          of the ‘vim-’ prefix in the package’s name.
        • With ‘#:neovim’ it is possible to add this package to Neovim’s
          packpath, in addition to if it is added automatically because
          of the ‘neovim-’ prefix in the package’s name.
        • With ‘#:mode’ it is possible to adjust the path which the
          plugin is installed into.  By default the plugin is installed
          into ‘start’ and other options are available, including ‘opt’.
          Adding a plugin into ‘opt’ will mean you will need to run, for
          example, ‘:packadd foo’ to load the ‘foo’ plugin from inside
          of Vim.

 -- Variable: clojure-build-system
     This variable is exported by ‘(guix build-system clojure)’.  It
     implements a simple build procedure for Clojure
     (https://clojure.org/) packages using plain old ‘compile’ in
     Clojure.  Cross-compilation is not supported yet.

     It adds ‘clojure’, ‘icedtea’ and ‘zip’ to the set of inputs.
     Different packages can be specified with the ‘#:clojure’, ‘#:jdk’
     and ‘#:zip’ parameters, respectively.

     A list of source directories, test directories and jar names can be
     specified with the ‘#:source-dirs’, ‘#:test-dirs’ and ‘#:jar-names’
     parameters, respectively.  Compile directory and main class can be
     specified with the ‘#:compile-dir’ and ‘#:main-class’ parameters,
     respectively.  Other parameters are documented below.

     This build system is an extension of ‘ant-build-system’, but with
     the following phases changed:

     ‘build’
          This phase calls ‘compile’ in Clojure to compile source files
          and runs ‘jar’ to create jars from both source files and
          compiled files according to the include list and exclude list
          specified in ‘#:aot-include’ and ‘#:aot-exclude’,
          respectively.  The exclude list has priority over the include
          list.  These lists consist of symbols representing Clojure
          libraries or the special keyword ‘#:all’ representing all
          Clojure libraries found under the source directories.  The
          parameter ‘#:omit-source?’ decides if source should be
          included into the jars.

     ‘check’
          This phase runs tests according to the include list and
          exclude list specified in ‘#:test-include’ and
          ‘#:test-exclude’, respectively.  Their meanings are analogous
          to that of ‘#:aot-include’ and ‘#:aot-exclude’, except that
          the special keyword ‘#:all’ now stands for all Clojure
          libraries found under the test directories.  The parameter
          ‘#:tests?’ decides if tests should be run.

     ‘install’
          This phase installs all jars built previously.

     Apart from the above, this build system also contains an additional
     phase:

     ‘install-doc’
          This phase installs all top-level files with base name
          matching ‘%doc-regex’.  A different regex can be specified
          with the ‘#:doc-regex’ parameter.  All files (recursively)
          inside the documentation directories specified in ‘#:doc-dirs’
          are installed as well.

 -- Variable: cmake-build-system
     This variable is exported by ‘(guix build-system cmake)’.  It
     implements the build procedure for packages using the CMake build
     tool (https://www.cmake.org).

     This build system adds the following keyword parameters to the ones
     defined by ‘gnu-build-system’:

     ‘#:cmake’
          The ‘cmake’ package is added to the set of inputs.  Which
          package is used can be specified with the ‘#:cmake’ parameter.

     ‘#:build-type’
          The ‘#:build-type’ parameter specifies in abstract terms the
          flags passed to the compiler; it defaults to
          ‘"RelWithDebInfo"’ (short for “release mode with debugging
          information”), which roughly means that code is compiled with
          ‘-O2 -g’, as is the case for Autoconf-based packages by
          default.

     ‘#:generator’
          This parameter specifies the CMake generator
          (https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html)
          responsible for writing the input files for the native build
          system.

     ‘#:test-exclude’
          Tests matching this regular expression are excluded from
          testing by ctest
          (https://cmake.org/cmake/help/latest/manual/ctest.1.html).

     ‘#:test-repeat-until-pass?’
          Directs ctest
          (https://cmake.org/cmake/help/latest/manual/ctest.1.html) to
          repeat
          (https://cmake.org/cmake/help/latest/manual/ctest.1.html#cmdoption-ctest-repeat)
          failed tests up to ‘#:test-repeat-until-pass-count’ times and
          is enabled by default.

     ‘#:test-repeat-until-pass-count’
          When ‘#:test-repeat-until-pass?’ is enabled this parameter
          sets the maximum number of failures for each test.  The
          default is ‘5’.

 -- Variable: composer-build-system
     This variable is exported by ‘(guix build-system composer)’.  It
     implements the build procedure for packages using Composer
     (https://getcomposer.org/), the PHP package manager.

     It automatically adds the ‘php’ package to the set of inputs.
     Which package is used can be specified with the ‘#:php’ parameter.

     The ‘#:test-target’ parameter is used to control which script is
     run for the tests.  By default, the ‘test’ script is run if it
     exists.  If the script does not exist, the build system will run
     ‘phpunit’ from the source directory, assuming there is a
     ‘phpunit.xml’ file.

 -- Variable: dune-build-system
     This variable is exported by ‘(guix build-system dune)’.  It
     supports builds of packages using Dune (https://dune.build/), a
     build tool for the OCaml programming language.  It is implemented
     as an extension of the ‘ocaml-build-system’ which is described
     below.  As such, the ‘#:ocaml’ and ‘#:findlib’ parameters can be
     passed to this build system.

     It automatically adds the ‘dune’ package to the set of inputs.
     Which package is used can be specified with the ‘#:dune’ parameter.

     There is no ‘configure’ phase because dune packages typically don’t
     need to be configured.  The ‘#:build-flags’ parameter is taken as a
     list of flags passed to the ‘dune’ command during the build.

     The ‘#:jbuild?’ parameter can be passed to use the ‘jbuild’ command
     instead of the more recent ‘dune’ command while building a package.
     Its default value is ‘#f’.

     The ‘#:package’ parameter can be passed to specify a package name,
     which is useful when a package contains multiple packages and you
     want to build only one of them.  This is equivalent to passing the
     ‘-p’ argument to ‘dune’.

 -- Variable: elm-build-system
     This variable is exported by ‘(guix build-system elm)’.  It
     implements a build procedure for Elm (https://elm-lang.org)
     packages similar to ‘elm install’.

     The build system adds an Elm compiler package to the set of inputs.
     The default compiler package (currently ‘elm-sans-reactor’) can be
     overridden using the ‘#:elm’ argument.  Additionally, Elm packages
     needed by the build system itself are added as implicit inputs if
     they are not already present: to suppress this behavior, use the
     ‘#:implicit-elm-package-inputs?’ argument, which is primarily
     useful for bootstrapping.

     The ‘"dependencies"’ and ‘"test-dependencies"’ in an Elm package’s
     ‘elm.json’ file correspond to ‘propagated-inputs’ and ‘inputs’,
     respectively.

     Elm requires a particular structure for package names: *note Elm
     Packages:: for more details, including utilities provided by ‘(guix
     build-system elm)’.

     There are currently a few noteworthy limitations to
     ‘elm-build-system’:

        • The build system is focused on “packages” in the Elm sense of
          the word: Elm “projects” which declare ‘{ "type": "package" }’
          in their ‘elm.json’ files.  Using ‘elm-build-system’ to build
          Elm “applications” (which declare ‘{ "type": "application" }’)
          is possible, but requires ad-hoc modifications to the build
          phases.  For examples, see the definitions of the
          ‘elm-todomvc’ example application and the ‘elm’ package itself
          (because the front-end for the ‘elm reactor’ command is an Elm
          application).

        • Elm supports multiple versions of a package coexisting
          simultaneously under ‘ELM_HOME’, but this does not yet work
          well with ‘elm-build-system’.  This limitation primarily
          affects Elm applications, because they specify exact versions
          for their dependencies, whereas Elm packages specify supported
          version ranges.  As a workaround, the example applications
          mentioned above use the ‘patch-application-dependencies’
          procedure provided by ‘(guix build elm-build-system)’ to
          rewrite their ‘elm.json’ files to refer to the package
          versions actually present in the build environment.
          Alternatively, Guix package transformations (*note Defining
          Package Variants::) could be used to rewrite an application’s
          entire dependency graph.

        • We are not yet able to run tests for Elm projects because
          neither ‘elm-test-rs’
          (https://github.com/mpizenberg/elm-test-rs) nor the
          Node.js-based ‘elm-test’
          (https://github.com/rtfeldman/node-test-runner) runner has
          been packaged for Guix yet.

 -- Variable: go-build-system
     This variable is exported by ‘(guix build-system go)’.  It
     implements a build procedure for Go packages using the standard Go
     build mechanisms
     (https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies).

     The user is expected to provide a value for the key ‘#:import-path’
     and, in some cases, ‘#:unpack-path’.  The import path
     (https://golang.org/doc/code.html#ImportPaths) corresponds to the
     file system path expected by the package’s build scripts and any
     referring packages, and provides a unique way to refer to a Go
     package.  It is typically based on a combination of the package
     source code’s remote URI and file system hierarchy structure.  In
     some cases, you will need to unpack the package’s source code to a
     different directory structure than the one indicated by the import
     path, and ‘#:unpack-path’ should be used in such cases.

     Packages that provide Go libraries should install their source code
     into the built output.  The key ‘#:install-source?’, which defaults
     to ‘#t’, controls whether or not the source code is installed.  It
     can be set to ‘#f’ for packages that only provide executable files.

     Packages can be cross-built, and if a specific architecture or
     operating system is desired then the keywords ‘#:goarch’ and
     ‘#:goos’ can be used to force the package to be built for that
     architecture and operating system.  The combinations known to Go
     can be found in their documentation
     (https://golang.org/doc/install/source#environment).

     The key ‘#:go’ can be used to specify the Go compiler package with
     which to build the package.

     The phase ‘check’ provides a wrapper for ‘go test’ which builds a
     test binary (or multiple binaries), vets the code and then runs the
     test binary.  Build, test and test binary flags can be provided as
     ‘#:test-flags’ parameter, default is ‘'()’.  See ‘go help test’ and
     ‘go help testflag’ for more details.

     The key ‘#:embed-files’, default is ‘'()’, provides a list of
     future embedded files or regexps matching files.  They will be
     copied to build directory after ‘unpack’ phase.  See
     <https://pkg.go.dev/embed> for more details.

 -- Variable: glib-or-gtk-build-system
     This variable is exported by ‘(guix build-system glib-or-gtk)’.  It
     is intended for use with packages making use of GLib or GTK+.

     This build system adds the following two phases to the ones defined
     by ‘gnu-build-system’:

     ‘glib-or-gtk-wrap’
          The phase ‘glib-or-gtk-wrap’ ensures that programs in ‘bin/’
          are able to find GLib “schemas” and GTK+ modules
          (https://developer.gnome.org/gtk3/stable/gtk-running.html).
          This is achieved by wrapping the programs in launch scripts
          that appropriately set the ‘XDG_DATA_DIRS’ and ‘GTK_PATH’
          environment variables.

          It is possible to exclude specific package outputs from that
          wrapping process by listing their names in the
          ‘#:glib-or-gtk-wrap-excluded-outputs’ parameter.  This is
          useful when an output is known not to contain any GLib or GTK+
          binaries, and where wrapping would gratuitously add a
          dependency of that output on GLib and GTK+.

     ‘glib-or-gtk-compile-schemas’
          The phase ‘glib-or-gtk-compile-schemas’ makes sure that all
          GSettings schemas
          (https://developer.gnome.org/gio/stable/glib-compile-schemas.html)
          of GLib are compiled.  Compilation is performed by the
          ‘glib-compile-schemas’ program.  It is provided by the package
          ‘glib:bin’ which is automatically imported by the build
          system.  The ‘glib’ package providing ‘glib-compile-schemas’
          can be specified with the ‘#:glib’ parameter.

     Both phases are executed after the ‘install’ phase.

 -- Variable: guile-build-system
     This build system is for Guile packages that consist exclusively of
     Scheme code and that are so lean that they don’t even have a
     makefile, let alone a ‘configure’ script.  It compiles Scheme code
     using ‘guild compile’ (*note (guile)Compilation::) and installs the
     ‘.scm’ and ‘.go’ files in the right place.  It also installs
     documentation.

     This build system supports cross-compilation by using the
     ‘--target’ option of ‘guild compile’.

     Packages built with ‘guile-build-system’ must provide a Guile
     package in their ‘native-inputs’ field.

 -- Variable: julia-build-system
     This variable is exported by ‘(guix build-system julia)’.  It
     implements the build procedure used by julia
     (https://julialang.org/) packages, which essentially is similar to
     running ‘julia -e 'using Pkg; Pkg.add(package)'’ in an environment
     where ‘JULIA_LOAD_PATH’ contains the paths to all Julia package
     inputs.  Tests are run by calling ‘/test/runtests.jl’.

     The Julia package name and uuid is read from the file
     ‘Project.toml’.  These values can be overridden by passing the
     argument ‘#:julia-package-name’ (which must be correctly
     capitalized) or ‘#:julia-package-uuid’.

     Julia packages usually manage their binary dependencies via
     ‘JLLWrappers.jl’, a Julia package that creates a module (named
     after the wrapped library followed by ‘_jll.jl’.

     To add the binary path ‘_jll.jl’ packages, you need to patch the
     files under ‘src/wrappers/’, replacing the call to the macro
     ‘JLLWrappers.@generate_wrapper_header’, adding as a second argument
     containing the store path the binary.

     As an example, in the MbedTLS Julia package, we add a build phase
     (*note Build Phases::) to insert the absolute file name of the
     wrapped MbedTLS package:

          (add-after 'unpack 'override-binary-path
            (lambda* (#:key inputs #:allow-other-keys)
              (for-each (lambda (wrapper)
                          (substitute* wrapper
                            (("generate_wrapper_header.*")
                             (string-append
                              "generate_wrapper_header(\"MbedTLS\", \""
                              (assoc-ref inputs "mbedtls") "\")\n"))))
                        ;; There's a Julia file for each platform, override them all.
                        (find-files "src/wrappers/" "\\.jl$"))))

     Some older packages that aren’t using ‘Project.toml’ yet, will
     require this file to be created, too.  It is internally done if the
     arguments ‘#:julia-package-name’ and ‘#:julia-package-uuid’ are
     provided.

 -- Variable: maven-build-system
     This variable is exported by ‘(guix build-system maven)’.  It
     implements a build procedure for Maven (https://maven.apache.org)
     packages.  Maven is a dependency and lifecycle management tool for
     Java.  A user of Maven specifies dependencies and plugins in a
     ‘pom.xml’ file that Maven reads.  When Maven does not have one of
     the dependencies or plugins in its repository, it will download
     them and use them to build the package.

     The maven build system ensures that maven will not try to download
     any dependency by running in offline mode.  Maven will fail if a
     dependency is missing.  Before running Maven, the ‘pom.xml’ (and
     subprojects) are modified to specify the version of dependencies
     and plugins that match the versions available in the guix build
     environment.  Dependencies and plugins must be installed in the
     fake maven repository at ‘lib/m2’, and are symlinked into a proper
     repository before maven is run.  Maven is instructed to use that
     repository for the build and installs built artifacts there.
     Changed files are copied to the ‘lib/m2’ directory of the package
     output.

     You can specify a ‘pom.xml’ file with the ‘#:pom-file’ argument, or
     let the build system use the default ‘pom.xml’ file in the sources.

     In case you need to specify a dependency’s version manually, you
     can use the ‘#:local-packages’ argument.  It takes an association
     list where the key is the groupId of the package and its value is
     an association list where the key is the artifactId of the package
     and its value is the version you want to override in the ‘pom.xml’.

     Some packages use dependencies or plugins that are not useful at
     runtime nor at build time in Guix.  You can alter the ‘pom.xml’
     file to remove them using the ‘#:exclude’ argument.  Its value is
     an association list where the key is the groupId of the plugin or
     dependency you want to remove, and the value is a list of
     artifactId you want to remove.

     You can override the default ‘jdk’ and ‘maven’ packages with the
     corresponding argument, ‘#:jdk’ and ‘#:maven’.

     The ‘#:maven-plugins’ argument is a list of maven plugins used
     during the build, with the same format as the ‘inputs’ fields of
     the package declaration.  Its default value is
     ‘(default-maven-plugins)’ which is also exported.

 -- Variable: minetest-mod-build-system
     This variable is exported by ‘(guix build-system minetest)’.  It
     implements a build procedure for Minetest
     (https://www.minetest.net) mods, which consists of copying Lua
     code, images and other resources to the location Minetest searches
     for mods.  The build system also minimises PNG images and verifies
     that Minetest can load the mod without errors.

 -- Variable: minify-build-system
     This variable is exported by ‘(guix build-system minify)’.  It
     implements a minification procedure for simple JavaScript packages.

     It adds ‘uglify-js’ to the set of inputs and uses it to compress
     all JavaScript files in the ‘src’ directory.  A different minifier
     package can be specified with the ‘#:uglify-js’ parameter, but it
     is expected that the package writes the minified code to the
     standard output.

     When the input JavaScript files are not all located in the ‘src’
     directory, the parameter ‘#:javascript-files’ can be used to
     specify a list of file names to feed to the minifier.

 -- Variable: mix-build-system
     This is a variable exported by ‘guix build-system mix’.  It
     implements the standard build procedure used by Elixr programs with
     Mix (https://hexdocs.pm/mix/Mix.html), which consists of running
     ‘mix compile’, thereby creating bytecode.

     The API is similar to the GNU-BUILD-SYSTEM, with some specifics for
     Elixir:
        • ‘#:tests?’ is a boolean, ‘#true’ by default, determining
          whether tests for the current build have to be run or not.
        • ‘#:test-flags’ is a list of arguments append to the ‘mix test’
          invocation.  It defaults to ‘'()’.
        • ‘#:mix-exs’, changes the full path to the ‘mix.exs’ file.  It
          defaults to ‘"mix.exs"’.  Please refer to upstream
          (https://hexdocs.pm/mix/Mix.html#module-environment-variables)
          documentation for more details.
        • ‘#:mix-path’, appends extra code paths.  It defaults to ‘#f’.
          Please refer to upstream
          (https://hexdocs.pm/mix/Mix.html#module-environment-variables)
          documentation for more details.

 -- Variable: mozilla-build-system
     This variable is exported by ‘(guix build-system mozilla)’.  It
     sets the ‘--target’ and ‘--host’ configuration flags to what
     software developed by Mozilla expects – due to historical reasons,
     Mozilla software expects ‘--host’ to be the system that is
     cross-compiled from and ‘--target’ to be the system that is
     cross-compiled to, contrary to the standard Autotools conventions.

 -- Variable: ocaml-build-system
     This variable is exported by ‘(guix build-system ocaml)’.  It
     implements a build procedure for OCaml (https://ocaml.org)
     packages, which consists of choosing the correct set of commands to
     run for each package.  OCaml packages can expect many different
     commands to be run.  This build system will try some of them.

     When the package has a ‘setup.ml’ file present at the top-level, it
     will run ‘ocaml setup.ml -configure’, ‘ocaml setup.ml -build’ and
     ‘ocaml setup.ml -install’.  The build system will assume that this
     file was generated by OASIS (http://oasis.forge.ocamlcore.org/) and
     will take care of setting the prefix and enabling tests if they are
     not disabled.  You can pass configure and build flags with the
     ‘#:configure-flags’ and ‘#:build-flags’.  The ‘#:test-flags’ key
     can be passed to change the set of flags used to enable tests.  The
     ‘#:use-make?’ key can be used to bypass this system in the build
     and install phases.

     When the package has a ‘configure’ file, it is assumed that it is a
     hand-made configure script that requires a different argument
     format than in the ‘gnu-build-system’.  You can add more flags with
     the ‘#:configure-flags’ key.

     When the package has a ‘Makefile’ file (or ‘#:use-make?’ is ‘#t’),
     it will be used and more flags can be passed to the build and
     install phases with the ‘#:make-flags’ key.

     Finally, some packages do not have these files and use a somewhat
     standard location for its build system.  In that case, the build
     system will run ‘ocaml pkg/pkg.ml’ or ‘ocaml pkg/build.ml’ and take
     care of providing the path to the required findlib module.
     Additional flags can be passed via the ‘#:build-flags’ key.
     Install is taken care of by ‘opam-installer’.  In this case, the
     ‘opam’ package must be added to the ‘native-inputs’ field of the
     package definition.

     Note that most OCaml packages assume they will be installed in the
     same directory as OCaml, which is not what we want in guix.  In
     particular, they will install ‘.so’ files in their module’s
     directory, which is usually fine because it is in the OCaml
     compiler directory.  In guix though, these libraries cannot be
     found and we use ‘CAML_LD_LIBRARY_PATH’.  This variable points to
     ‘lib/ocaml/site-lib/stubslibs’ and this is where ‘.so’ libraries
     should be installed.

 -- Variable: python-build-system
     This variable is exported by ‘(guix build-system python)’.  It
     implements the more or less standard build procedure used by Python
     packages, which consists in running ‘python setup.py build’ and
     then ‘python setup.py install --prefix=/gnu/store/...’.

     For packages that install stand-alone Python programs under ‘bin/’,
     it takes care of wrapping these programs so that their
     ‘GUIX_PYTHONPATH’ environment variable points to all the Python
     libraries they depend on.

     Which Python package is used to perform the build can be specified
     with the ‘#:python’ parameter.  This is a useful way to force a
     package to be built for a specific version of the Python
     interpreter, which might be necessary if the package is only
     compatible with a single interpreter version.

     By default guix calls ‘setup.py’ under control of ‘setuptools’,
     much like ‘pip’ does.  Some packages are not compatible with
     setuptools (and pip), thus you can disable this by setting the
     ‘#:use-setuptools?’ parameter to ‘#f’.

     If a ‘"python"’ output is available, the package is installed into
     it instead of the default ‘"out"’ output.  This is useful for
     packages that include a Python package as only a part of the
     software, and thus want to combine the phases of
     ‘python-build-system’ with another build system.  Python bindings
     are a common usecase.

 -- Variable: pyproject-build-system
     This is a variable exported by ‘guix build-system pyproject’.  It
     is based on PYTHON-BUILD-SYSTEM, and adds support for
     ‘pyproject.toml’ and PEP 517 (https://peps.python.org/pep-0517/).
     It also supports a variety of build backends and test frameworks.

     The API is slightly different from PYTHON-BUILD-SYSTEM:
        • ‘#:use-setuptools?’ and ‘#:test-target’ is removed.
        • ‘#:configure-flags’ is changed.  Instead of a list this option
          must be a JSON object, whose interpretation depends on the
          build backend.  For instance the example from PEP 517
          (https://peps.python.org/pep-0517/#config-settings) should be
          written as ‘'(@ ("CC" "gcc") ("--global-option"
          ("--some-global-option")) ("--build-option" ("--build-option1"
          "--build-option2")))’
        • ‘#:backend-path’ is added.  It defaults to ‘#false’, but when
          set to a list it will be appended to Python’s search path and
          overrides the definition in ‘pyproject.toml’.
        • ‘#:build-backend’ is added.  It defaults to ‘#false’ and will
          try to guess the appropriate backend based on
          ‘pyproject.toml’.
        • ‘#:test-backend’ is added.  It defaults to ‘#false’ and will
          guess an appropriate test backend based on what is available
          in package inputs.
        • ‘#:test-flags’ is added.  The default is ‘'()’.  These flags
          are passed as arguments to the test command.  Note that flags
          for verbose output is always enabled on supported backends.

     It is considered “experimental” in that the implementation details
     are not set in stone yet, however users are encouraged to try it
     for new Python projects (even those using ‘setup.py’).  The API is
     subject to change, but any breaking changes in the Guix channel
     will be dealt with.

     Eventually this build system will be deprecated and merged back
     into PYTHON-BUILD-SYSTEM, probably some time in 2024.

 -- Variable: perl-build-system
     This variable is exported by ‘(guix build-system perl)’.  It
     implements the standard build procedure for Perl packages, which
     either consists in running ‘perl Build.PL --prefix=/gnu/store/...’,
     followed by ‘Build’ and ‘Build install’; or in running ‘perl
     Makefile.PL PREFIX=/gnu/store/...’, followed by ‘make’ and ‘make
     install’, depending on which of ‘Build.PL’ or ‘Makefile.PL’ is
     present in the package distribution.  Preference is given to the
     former if both ‘Build.PL’ and ‘Makefile.PL’ exist in the package
     distribution.  This preference can be reversed by specifying ‘#t’
     for the ‘#:make-maker?’ parameter.

     The initial ‘perl Makefile.PL’ or ‘perl Build.PL’ invocation passes
     flags specified by the ‘#:make-maker-flags’ or
     ‘#:module-build-flags’ parameter, respectively.

     Which Perl package is used can be specified with ‘#:perl’.

 -- Variable: renpy-build-system
     This variable is exported by ‘(guix build-system renpy)’.  It
     implements the more or less standard build procedure used by Ren’py
     games, which consists of loading ‘#:game’ once, thereby creating
     bytecode for it.

     It further creates a wrapper script in ‘bin/’ and a desktop entry
     in ‘share/applications’, both of which can be used to launch the
     game.

     Which Ren’py package is used can be specified with ‘#:renpy’.
     Games can also be installed in outputs other than “out” by using
     ‘#:output’.

 -- Variable: qt-build-system
     This variable is exported by ‘(guix build-system qt)’.  It is
     intended for use with applications using Qt or KDE.

     This build system adds the following two phases to the ones defined
     by ‘cmake-build-system’:

     ‘check-setup’
          The phase ‘check-setup’ prepares the environment for running
          the checks as commonly used by Qt test programs.  For now this
          only sets some environment variables:
          ‘QT_QPA_PLATFORM=offscreen’, ‘DBUS_FATAL_WARNINGS=0’ and
          ‘CTEST_OUTPUT_ON_FAILURE=1’.

          This phase is added before the ‘check’ phase.  It’s a separate
          phase to ease adjusting if necessary.

     ‘qt-wrap’
          The phase ‘qt-wrap’ searches for Qt5 plugin paths, QML paths
          and some XDG in the inputs and output.  In case some path is
          found, all programs in the output’s ‘bin/’, ‘sbin/’,
          ‘libexec/’ and ‘lib/libexec/’ directories are wrapped in
          scripts defining the necessary environment variables.

          It is possible to exclude specific package outputs from that
          wrapping process by listing their names in the
          ‘#:qt-wrap-excluded-outputs’ parameter.  This is useful when
          an output is known not to contain any Qt binaries, and where
          wrapping would gratuitously add a dependency of that output on
          Qt, KDE, or such.

          This phase is added after the ‘install’ phase.

 -- Variable: r-build-system
     This variable is exported by ‘(guix build-system r)’.  It
     implements the build procedure used by R (https://r-project.org)
     packages, which essentially is little more than running ‘R CMD
     INSTALL --library=/gnu/store/...’ in an environment where
     ‘R_LIBS_SITE’ contains the paths to all R package inputs.  Tests
     are run after installation using the R function
     ‘tools::testInstalledPackage’.

 -- Variable: rakudo-build-system
     This variable is exported by ‘(guix build-system rakudo)’.  It
     implements the build procedure used by Rakudo (https://rakudo.org/)
     for Perl6 (https://perl6.org/) packages.  It installs the package
     to ‘/gnu/store/.../NAME-VERSION/share/perl6’ and installs the
     binaries, library files and the resources, as well as wrap the
     files under the ‘bin/’ directory.  Tests can be skipped by passing
     ‘#f’ to the ‘tests?’ parameter.

     Which rakudo package is used can be specified with ‘rakudo’.  Which
     perl6-tap-harness package used for the tests can be specified with
     ‘#:prove6’ or removed by passing ‘#f’ to the ‘with-prove6?’
     parameter.  Which perl6-zef package used for tests and installing
     can be specified with ‘#:zef’ or removed by passing ‘#f’ to the
     ‘with-zef?’ parameter.

 -- Variable: rebar-build-system
     This variable is exported by ‘(guix build-system rebar)’.  It
     implements a build procedure around rebar3 (https://rebar3.org), a
     build system for programs written in the Erlang language.

     It adds both ‘rebar3’ and the ‘erlang’ to the set of inputs.
     Different packages can be specified with the ‘#:rebar’ and
     ‘#:erlang’ parameters, respectively.

     This build system is based on ‘gnu-build-system’, but with the
     following phases changed:

     ‘unpack’
          This phase, after unpacking the source like the
          ‘gnu-build-system’ does, checks for a file ‘contents.tar.gz’
          at the top-level of the source.  If this file exists, it will
          be unpacked, too.  This eases handling of package hosted at
          <https://hex.pm/>, the Erlang and Elixir package repository.

     ‘bootstrap’
     ‘configure’
          There are no ‘bootstrap’ and ‘configure’ phase because erlang
          packages typically don’t need to be configured.

     ‘build’
          This phase runs ‘rebar3 compile’ with the flags listed in
          ‘#:rebar-flags’.

     ‘check’
          Unless ‘#:tests? #f’ is passed, this phase runs ‘rebar3
          eunit’, or some other target specified with ‘#:test-target’,
          with the flags listed in ‘#:rebar-flags’,

     ‘install’
          This installs the files created in the default profile, or
          some other profile specified with ‘#:install-profile’.

 -- Variable: texlive-build-system
     This variable is exported by ‘(guix build-system texlive)’.  It is
     used to build TeX packages in batch mode with a specified engine.
     The build system sets the ‘TEXINPUTS’ variable to find all TeX
     source files in the inputs.

     By default it tries to run ‘luatex’ on all ‘.ins’ files, and if it
     fails to find any, on all ‘.dtx’ files.  A different engine and
     format can be specified with, respectively, the ‘#:tex-engine’ and
     ‘#:tex-format’ arguments.  Different build targets can be specified
     with the ‘#:build-targets’ argument, which expects a list of file
     names.

     It also generates font metrics (i.e., ‘.tfm’ files) out of Metafont
     files whenever possible.  Likewise, it can also create TeX formats
     (i.e., ‘.fmt’ files) listed in the ‘#:create-formats’ argument, and
     generate a symbolic link from ‘bin/’ directory to any script
     located in ‘texmf-dist/scripts/’, provided its file name is listed
     in ‘#:link-scripts’ argument.

     The build system adds ‘texlive-bin’ from ‘(gnu packages tex)’ to
     the native inputs.  It can be overridden with the ‘#:texlive-bin’
     argument.

     The package ‘texlive-latex-bin’, from the same module, contains
     most of the tools for building TeX Live packages; for convenience,
     it is also added by default to the native inputs.  However, this
     can be troublesome when building a dependency of
     ‘texlive-latex-bin’ itself.  In this particular situation, the
     ‘#:texlive-latex-bin?’ argument should be set to ‘#f’.

 -- Variable: ruby-build-system
     This variable is exported by ‘(guix build-system ruby)’.  It
     implements the RubyGems build procedure used by Ruby packages,
     which involves running ‘gem build’ followed by ‘gem install’.

     The ‘source’ field of a package that uses this build system
     typically references a gem archive, since this is the format that
     Ruby developers use when releasing their software.  The build
     system unpacks the gem archive, potentially patches the source,
     runs the test suite, repackages the gem, and installs it.
     Additionally, directories and tarballs may be referenced to allow
     building unreleased gems from Git or a traditional source release
     tarball.

     Which Ruby package is used can be specified with the ‘#:ruby’
     parameter.  A list of additional flags to be passed to the ‘gem’
     command can be specified with the ‘#:gem-flags’ parameter.

 -- Variable: waf-build-system
     This variable is exported by ‘(guix build-system waf)’.  It
     implements a build procedure around the ‘waf’ script.  The common
     phases—‘configure’, ‘build’, and ‘install’—are implemented by
     passing their names as arguments to the ‘waf’ script.

     The ‘waf’ script is executed by the Python interpreter.  Which
     Python package is used to run the script can be specified with the
     ‘#:python’ parameter.

 -- Variable: zig-build-system
     This variable is exported by ‘(guix build-system zig)’.  It
     implements the build procedures for the Zig (https://ziglang.org/)
     build system (‘zig build’ command).

     Selecting this build system adds ‘zig’ to the package inputs, in
     addition to the packages of ‘gnu-build-system’.

     This build system by default installs package source to output.
     This behavior can be disabled by setting ‘#:install-source?’
     parameter to ‘#f’.

     For packages that don’t install anything and don’t come with a test
     suite (likely library packages to be used by other Zig packages),
     you can set ‘#:skip-build?’ parameter to ‘#t’, which skips ‘build’
     and ‘check’ phases.

     The ‘configure’ phase sets up environment for ‘zig build’.  You
     need to add custom phases after it if you want to invoke ‘zig’.

     The ‘#:zig-build-flags’ parameter is a list of flags that are
     passed to ‘zig build’ in ‘build’ phase.  The ‘#:zig-test-flags’
     parameter is a list of flags that are passed to ‘zig build test’ in
     ‘check’ phase.  The default compiler package can be overridden with
     the ‘#:zig’ parameter.

     The optional ‘#:zig-release-type’ parameter declares the type of
     release.  Possible values are: ‘"safe"’, ‘"fast"’, or ‘"small"’.
     The default value is ‘#f’, which causes the release flag to be
     omitted from the ‘zig’ command and results in a ‘"debug"’ build.

 -- Variable: scons-build-system
     This variable is exported by ‘(guix build-system scons)’.  It
     implements the build procedure used by the SCons software
     construction tool.  This build system runs ‘scons’ to build the
     package, ‘scons test’ to run tests, and then ‘scons install’ to
     install the package.

     Additional flags to be passed to ‘scons’ can be specified with the
     ‘#:scons-flags’ parameter.  The default build and install targets
     can be overridden with ‘#:build-targets’ and ‘#:install-targets’
     respectively.  The version of Python used to run SCons can be
     specified by selecting the appropriate SCons package with the
     ‘#:scons’ parameter.

 -- Variable: hare-build-system
     This variable is exported by ‘(guix build-system hare)’.  It
     implements the Makefile build process typically used by Hare
     packages, removing the ‘configure’ phase used by ‘gnu-build-system’
     and modifying existing phases to set the Hare architecture tag,
     module path, and package install destinations appropriately.

     This relies on the package’s Makefile supporting, at minimum, the
     variables ‘HAREFLAGS’ and ‘THIRDPARTYDIR’.  Packages may set
     ‘make-flags’ to override or supplement these variables.

     By default, Hare modules are installed to the ‘lib’ output if it
     exists, and all other files to the ‘bin’ output.  If an output does
     not exist, the default ‘out’ output is used instead.  This behavior
     may be overriden through the ‘#:binary-output’ and
     ‘#:module-output’ keyword arguments.

     ‘(guix build-system hare)’ also provides utility definitions for
     creating Hare packages.  The variable ‘%hare-supported-systems’ is
     the list of build targets currently supported by ‘hare’, for use in
     ‘supported-systems’ (*note package Reference::).  The procedure
     ‘target->hare-arch’ may be used to get the Hare architecture tag
     for a given (supported) Guix target or system.

 -- Variable: haskell-build-system
     This variable is exported by ‘(guix build-system haskell)’.  It
     implements the Cabal build procedure used by Haskell packages,
     which involves running ‘runhaskell Setup.hs configure
     --prefix=/gnu/store/...’ and ‘runhaskell Setup.hs build’.  Instead
     of installing the package by running ‘runhaskell Setup.hs install’,
     to avoid trying to register libraries in the read-only compiler
     store directory, the build system uses ‘runhaskell Setup.hs copy’,
     followed by ‘runhaskell Setup.hs register’.  In addition, the build
     system generates the package documentation by running ‘runhaskell
     Setup.hs haddock’, unless ‘#:haddock? #f’ is passed.  Optional
     Haddock parameters can be passed with the help of the
     ‘#:haddock-flags’ parameter.  If the file ‘Setup.hs’ is not found,
     the build system looks for ‘Setup.lhs’ instead.

     Which Haskell compiler is used can be specified with the
     ‘#:haskell’ parameter which defaults to ‘ghc’.

 -- Variable: dub-build-system
     This variable is exported by ‘(guix build-system dub)’.  It
     implements the Dub build procedure used by D packages, which
     involves running ‘dub build’ and ‘dub run’.  Installation is done
     by copying the files manually.

     Which D compiler is used can be specified with the ‘#:ldc’
     parameter which defaults to ‘ldc’.

 -- Variable: emacs-build-system
     This variable is exported by ‘(guix build-system emacs)’.  It
     implements an installation procedure similar to the packaging
     system of Emacs itself (*note (emacs)Packages::).

     It first creates the ‘package-autoloads.el’ file, then it byte
     compiles all Emacs Lisp files.  Differently from the Emacs
     packaging system, the Info documentation files are moved to the
     standard documentation directory and the ‘dir’ file is deleted.
     The Elisp package files are installed directly under
     ‘share/emacs/site-lisp’.

 -- Variable: font-build-system
     This variable is exported by ‘(guix build-system font)’.  It
     implements an installation procedure for font packages where
     upstream provides pre-compiled TrueType, OpenType, etc. font files
     that merely need to be copied into place.  It copies font files to
     standard locations in the output directory.

 -- Variable: meson-build-system
     This variable is exported by ‘(guix build-system meson)’.  It
     implements the build procedure for packages that use Meson
     (https://mesonbuild.com) as their build system.

     It adds both Meson and Ninja (https://ninja-build.org/) to the set
     of inputs, and they can be changed with the parameters ‘#:meson’
     and ‘#:ninja’ if needed.

     This build system is an extension of ‘gnu-build-system’, but with
     the following phases changed to some specific for Meson:

     ‘configure’
          The phase runs ‘meson’ with the flags specified in
          ‘#:configure-flags’.  The flag ‘--buildtype’ is always set to
          ‘debugoptimized’ unless something else is specified in
          ‘#:build-type’.

     ‘build’
          The phase runs ‘ninja’ to build the package in parallel by
          default, but this can be changed with ‘#:parallel-build?’.

     ‘check’
          The phase runs ‘meson test’ with a base set of options that
          cannot be overridden.  This base set of options can be
          extended via the ‘#:test-options’ argument, for example to
          select or skip a specific test suite.

     ‘install’
          The phase runs ‘ninja install’ and can not be changed.

     Apart from that, the build system also adds the following phases:

     ‘fix-runpath’
          This phase ensures that all binaries can find the libraries
          they need.  It searches for required libraries in
          subdirectories of the package being built, and adds those to
          ‘RUNPATH’ where needed.  It also removes references to
          libraries left over from the build phase by ‘meson’, such as
          test dependencies, that aren’t actually required for the
          program to run.

     ‘glib-or-gtk-wrap’
          This phase is the phase provided by
          ‘glib-or-gtk-build-system’, and it is not enabled by default.
          It can be enabled with ‘#:glib-or-gtk?’.

     ‘glib-or-gtk-compile-schemas’
          This phase is the phase provided by
          ‘glib-or-gtk-build-system’, and it is not enabled by default.
          It can be enabled with ‘#:glib-or-gtk?’.

 -- Variable: linux-module-build-system
     ‘linux-module-build-system’ allows building Linux kernel modules.

     This build system is an extension of ‘gnu-build-system’, but with
     the following phases changed:

     ‘configure’
          This phase configures the environment so that the Linux
          kernel’s Makefile can be used to build the external kernel
          module.

     ‘build’
          This phase uses the Linux kernel’s Makefile in order to build
          the external kernel module.

     ‘install’
          This phase uses the Linux kernel’s Makefile in order to
          install the external kernel module.

     It is possible and useful to specify the Linux kernel to use for
     building the module (in the ‘arguments’ form of a package using the
     ‘linux-module-build-system’, use the key ‘#:linux’ to specify it).

 -- Variable: node-build-system
     This variable is exported by ‘(guix build-system node)’.  It
     implements the build procedure used by Node.js
     (https://nodejs.org), which implements an approximation of the ‘npm
     install’ command, followed by an ‘npm test’ command.

     Which Node.js package is used to interpret the ‘npm’ commands can
     be specified with the ‘#:node’ parameter which defaults to ‘node’.

 -- Variable: tree-sitter-build-system

     This variable is exported by ‘(guix build-system tree-sitter)’.  It
     implements procedures to compile grammars for the Tree-sitter
     (https://tree-sitter.github.io/tree-sitter/) parsing library.  It
     essentially runs ‘tree-sitter generate’ to translate ‘grammar.js’
     grammars to JSON and then to C. Which it then compiles to native
     code.

     Tree-sitter packages may support multiple grammars, so this build
     system supports a ‘#:grammar-directories’ keyword to specify a list
     of locations where a ‘grammar.js’ file may be found.

     Grammars sometimes depend on each other, such as C++ depending on C
     and TypeScript depending on JavaScript.  You may use inputs to
     declare such dependencies.

   Lastly, for packages that do not need anything as sophisticated, a
“trivial” build system is provided.  It is trivial in the sense that it
provides basically no support: it does not pull any implicit inputs, and
does not have a notion of build phases.

 -- Variable: trivial-build-system
     This variable is exported by ‘(guix build-system trivial)’.

     This build system requires a ‘#:builder’ argument.  This argument
     must be a Scheme expression that builds the package output(s)—as
     with ‘build-expression->derivation’ (*note
     ‘build-expression->derivation’: Derivations.).

 -- Variable: channel-build-system
     This variable is exported by ‘(guix build-system channel)’.

     This build system is meant primarily for internal use.  A package
     using this build system must have a channel specification as its
     ‘source’ field (*note Channels::); alternatively, its source can be
     a directory name, in which case an additional ‘#:commit’ argument
     must be supplied to specify the commit being built (a hexadecimal
     string).

     Optionally, a ‘#:channels’ argument specifying additional channels
     can be provided.

     The resulting package is a Guix instance of the given channel(s),
     similar to how ‘guix time-machine’ would build it.


File: guix.info,  Node: Build Phases,  Next: Build Utilities,  Prev: Build Systems,  Up: Programming Interface

8.6 Build Phases
================

Almost all package build systems implement a notion “build phases”: a
sequence of actions that the build system executes, when you build the
package, leading to the installed byproducts in the store.  A notable
exception is the “bare-bones” ‘trivial-build-system’ (*note Build
Systems::).

   As discussed in the previous section, those build systems provide a
standard list of phases.  For ‘gnu-build-system’, the main build phases
are the following:

‘set-paths’
     Define search path environment variables for all the input
     packages, including ‘PATH’ (*note Search Paths::).

‘unpack’
     Unpack the source tarball, and change the current directory to the
     extracted source tree.  If the source is actually a directory, copy
     it to the build tree, and enter that directory.

‘patch-source-shebangs’
     Patch shebangs encountered in source files so they refer to the
     right store file names.  For instance, this changes ‘#!/bin/sh’ to
     ‘#!/gnu/store/...-bash-4.3/bin/sh’.

‘configure’
     Run the ‘configure’ script with a number of default options, such
     as ‘--prefix=/gnu/store/...’, as well as the options specified by
     the ‘#:configure-flags’ argument.

‘build’
     Run ‘make’ with the list of flags specified with ‘#:make-flags’.
     If the ‘#:parallel-build?’ argument is true (the default), build
     with ‘make -j’.

‘check’
     Run ‘make check’, or some other target specified with
     ‘#:test-target’, unless ‘#:tests? #f’ is passed.  If the
     ‘#:parallel-tests?’ argument is true (the default), run ‘make check
     -j’.

‘install’
     Run ‘make install’ with the flags listed in ‘#:make-flags’.

‘patch-shebangs’
     Patch shebangs on the installed executable files.

‘strip’
     Strip debugging symbols from ELF files (unless ‘#:strip-binaries?’
     is false), copying them to the ‘debug’ output when available (*note
     Installing Debugging Files::).

‘validate-runpath’
     Validate the ‘RUNPATH’ of ELF binaries, unless
     ‘#:validate-runpath?’ is false (*note Build Systems::).

     This validation step consists in making sure that all the shared
     libraries needed by an ELF binary, which are listed as ‘DT_NEEDED’
     entries in its ‘PT_DYNAMIC’ segment, appear in the ‘DT_RUNPATH’
     entry of that binary.  In other words, it ensures that running or
     using those binaries will not result in a “file not found” error at
     run time.  *Note ‘-rpath’: (ld)Options, for more information on
     ‘RUNPATH’.

   Other build systems have similar phases, with some variations.  For
example, ‘cmake-build-system’ has same-named phases but its ‘configure’
phases runs ‘cmake’ instead of ‘./configure’.  Others, such as
‘python-build-system’, have a wholly different list of standard phases.
All this code runs on the “build side”: it is evaluated when you
actually build the package, in a dedicated build process spawned by the
build daemon (*note Invoking guix-daemon::).

   Build phases are represented as association lists or “alists” (*note
(guile)Association Lists::) where each key is a symbol for the name of
the phase and the associated value is a procedure that accepts an
arbitrary number of arguments.  By convention, those procedures receive
information about the build in the form of “keyword parameters”, which
they can use or ignore.

   For example, here is how ‘(guix build gnu-build-system)’ defines
‘%standard-phases’, the variable holding its alist of build phases(1):

     ;; The build phases of 'gnu-build-system'.

     (define* (unpack #:key source #:allow-other-keys)
       ;; Extract the source tarball.
       (invoke "tar" "xvf" source))

     (define* (configure #:key outputs #:allow-other-keys)
       ;; Run the 'configure' script.  Install to output "out".
       (let ((out (assoc-ref outputs "out")))
         (invoke "./configure"
                 (string-append "--prefix=" out))))

     (define* (build #:allow-other-keys)
       ;; Compile.
       (invoke "make"))

     (define* (check #:key (test-target "check") (tests? #true)
                     #:allow-other-keys)
       ;; Run the test suite.
       (if tests?
           (invoke "make" test-target)
           (display "test suite not run\n")))

     (define* (install #:allow-other-keys)
       ;; Install files to the prefix 'configure' specified.
       (invoke "make" "install"))

     (define %standard-phases
       ;; The list of standard phases (quite a few are omitted
       ;; for brevity).  Each element is a symbol/procedure pair.
       (list (cons 'unpack unpack)
             (cons 'configure configure)
             (cons 'build build)
             (cons 'check check)
             (cons 'install install)))

   This shows how ‘%standard-phases’ is defined as a list of
symbol/procedure pairs (*note (guile)Pairs::).  The first pair
associates the ‘unpack’ procedure with the ‘unpack’ symbol—a name; the
second pair defines the ‘configure’ phase similarly, and so on.  When
building a package that uses ‘gnu-build-system’ with its default list of
phases, those phases are executed sequentially.  You can see the name of
each phase started and completed in the build log of packages that you
build.

   Let’s now look at the procedures themselves.  Each one is defined
with ‘define*’: ‘#:key’ lists keyword parameters the procedure accepts,
possibly with a default value, and ‘#:allow-other-keys’ specifies that
other keyword parameters are ignored (*note (guile)Optional
Arguments::).

   The ‘unpack’ procedure honors the ‘source’ parameter, which the build
system uses to pass the file name of the source tarball (or version
control checkout), and it ignores other parameters.  The ‘configure’
phase only cares about the ‘outputs’ parameter, an alist mapping package
output names to their store file name (*note Packages with Multiple
Outputs::).  It extracts the file name of for ‘out’, the default output,
and passes it to ‘./configure’ as the installation prefix, meaning that
‘make install’ will eventually copy all the files in that directory
(*note configuration and makefile conventions:
(standards)Configuration.).  ‘build’ and ‘install’ ignore all their
arguments.  ‘check’ honors the ‘test-target’ argument, which specifies
the name of the Makefile target to run tests; it prints a message and
skips tests when ‘tests?’ is false.

   The list of phases used for a particular package can be changed with
the ‘#:phases’ parameter of the build system.  Changing the set of build
phases boils down to building a new alist of phases based on the
‘%standard-phases’ alist described above.  This can be done with
standard alist procedures such as ‘alist-delete’ (*note (guile)SRFI-1
Association Lists::); however, it is more convenient to do so with
‘modify-phases’ (*note ‘modify-phases’: Build Utilities.).

   Here is an example of a package definition that removes the
‘configure’ phase of ‘%standard-phases’ and inserts a new phase before
the ‘build’ phase, called ‘set-prefix-in-makefile’:

     (define-public example
       (package
         (name "example")
         ;; other fields omitted
         (build-system gnu-build-system)
         (arguments
          (list
           #:phases
           #~(modify-phases %standard-phases
               (delete 'configure)
               (add-before 'build 'set-prefix-in-makefile
                 (lambda* (#:key inputs #:allow-other-keys)
                   ;; Modify the makefile so that its
                   ;; 'PREFIX' variable points to #$output and
                   ;; 'XMLLINT' points to the correct path.
                   (substitute* "Makefile"
                     (("PREFIX =.*")
                      (string-append "PREFIX = " #$output "\n"))
                     (("XMLLINT =.*")
                      (string-append "XMLLINT = "
                                     (search-input-file inputs "/bin/xmllint")
                                     "\n"))))))))))

   The new phase that is inserted is written as an anonymous procedure,
introduced with ‘lambda*’; it looks for the ‘xmllint’ executable under a
‘/bin’ directory among the package’s inputs (*note package Reference::).
It also honors the ‘outputs’ parameter we have seen before.  *Note Build
Utilities::, for more about the helpers used by this phase, and for more
examples of ‘modify-phases’.

     Tip: You can inspect the code associated with a package’s
     ‘#:phases’ argument interactively, at the REPL (*note Using Guix
     Interactively::).

   Keep in mind that build phases are code evaluated at the time the
package is actually built.  This explains why the whole ‘modify-phases’
expression above is quoted (it comes after the ‘#~’ or hash-tilde): it
is “staged” for later execution.  *Note G-Expressions::, for an
explanation of code staging and the “code strata” involved.

   ---------- Footnotes ----------

   (1) We present a simplified view of those build phases, but do take a
look at ‘(guix build gnu-build-system)’ to see all the details!


File: guix.info,  Node: Build Utilities,  Next: Search Paths,  Prev: Build Phases,  Up: Programming Interface

8.7 Build Utilities
===================

As soon as you start writing non-trivial package definitions (*note
Defining Packages::) or other build actions (*note G-Expressions::), you
will likely start looking for helpers for “shell-like” actions—creating
directories, copying and deleting files recursively, manipulating build
phases, and so on.  The ‘(guix build utils)’ module provides such
utility procedures.

   Most build systems load ‘(guix build utils)’ (*note Build Systems::).
Thus, when writing custom build phases for your package definitions, you
can usually assume those procedures are in scope.

   When writing G-expressions, you can import ‘(guix build utils)’ on
the “build side” using ‘with-imported-modules’ and then put it in scope
with the ‘use-modules’ form (*note (guile)Using Guile Modules::):

     (with-imported-modules '((guix build utils))  ;import it
       (computed-file "empty-tree"
                      #~(begin
                          ;; Put it in scope.
                          (use-modules (guix build utils))

                          ;; Happily use its 'mkdir-p' procedure.
                          (mkdir-p (string-append #$output "/a/b/c")))))

   The remainder of this section is the reference for most of the
utility procedures provided by ‘(guix build utils)’.

8.7.1 Dealing with Store File Names
-----------------------------------

This section documents procedures that deal with store file names.

 -- Procedure: %store-directory
     Return the directory name of the store.

 -- Procedure: store-file-name? file
     Return true if FILE is in the store.

 -- Procedure: strip-store-file-name file
     Strip the ‘/gnu/store’ and hash from FILE, a store file name.  The
     result is typically a ‘"PACKAGE-VERSION"’ string.

 -- Procedure: package-name->name+version name
     Given NAME, a package name like ‘"foo-0.9.1b"’, return two values:
     ‘"foo"’ and ‘"0.9.1b"’.  When the version part is unavailable, NAME
     and ‘#f’ are returned.  The first hyphen followed by a digit is
     considered to introduce the version part.

8.7.2 File Types
----------------

The procedures below deal with files and file types.

 -- Procedure: directory-exists? dir
     Return ‘#t’ if DIR exists and is a directory.

 -- Procedure: executable-file? file
     Return ‘#t’ if FILE exists and is executable.

 -- Procedure: symbolic-link? file
     Return ‘#t’ if FILE is a symbolic link (aka.  a “symlink”).

 -- Procedure: elf-file? file
 -- Procedure: ar-file? file
 -- Procedure: gzip-file? file
     Return ‘#t’ if FILE is, respectively, an ELF file, an ‘ar’ archive
     (such as a ‘.a’ static library), or a gzip file.

 -- Procedure: reset-gzip-timestamp file [#:keep-mtime? #t]
     If FILE is a gzip file, reset its embedded timestamp (as with ‘gzip
     --no-name’) and return true.  Otherwise return ‘#f’.  When
     KEEP-MTIME? is true, preserve FILE’s modification time.

8.7.3 File Manipulation
-----------------------

The following procedures and macros help create, modify, and delete
files.  They provide functionality comparable to common shell utilities
such as ‘mkdir -p’, ‘cp -r’, ‘rm -r’, and ‘sed’.  They complement
Guile’s extensive, but low-level, file system interface (*note
(guile)POSIX::).

 -- Macro: with-directory-excursion directory body ...
     Run BODY with DIRECTORY as the process’s current directory.

     Essentially, this macro changes the current directory to DIRECTORY
     before evaluating BODY, using ‘chdir’ (*note (guile)Processes::).
     It changes back to the initial directory when the dynamic extent of
     BODY is left, be it via normal procedure return or via a non-local
     exit such as an exception.

 -- Procedure: mkdir-p dir
     Create directory DIR and all its ancestors.

 -- Procedure: install-file file directory
     Create DIRECTORY if it does not exist and copy FILE in there under
     the same name.

 -- Procedure: make-file-writable file
     Make FILE writable for its owner.

 -- Procedure: copy-recursively source destination [#:log
          (current-output-port)] [#:follow-symlinks? #f] [#:copy-file
          copy-file] [#:keep-mtime? #f] [#:keep-permissions? #t]
          [#:select? (const #t)]
     Copy SOURCE directory to DESTINATION.  Follow symlinks if
     FOLLOW-SYMLINKS? is true; otherwise, just preserve them.  Call
     COPY-FILE to copy regular files.  Call SELECT?, taking two
     arguments, FILE and STAT, for each entry in SOURCE, where FILE is
     the entry’s absolute file name and STAT is the result of ‘lstat’
     (or ‘stat’ if FOLLOW-SYMLINKS? is true); exclude entries for which
     SELECT? does not return true.  When KEEP-MTIME? is true, keep the
     modification time of the files in SOURCE on those of DESTINATION.
     When KEEP-PERMISSIONS? is true, preserve file permissions.  Write
     verbose output to the LOG port.

 -- Procedure: delete-file-recursively dir [#:follow-mounts? #f]
     Delete DIR recursively, like ‘rm -rf’, without following symlinks.
     Don’t follow mount points either, unless FOLLOW-MOUNTS? is true.
     Report but ignore errors.

 -- Macro: substitute* file ((regexp match-var...) body...) ...
     Substitute REGEXP in FILE by the string returned by BODY.  BODY is
     evaluated with each MATCH-VAR bound to the corresponding positional
     regexp sub-expression.  For example:

          (substitute* file
            (("hello")
             "good morning\n")
            (("foo([a-z]+)bar(.*)$" all letters end)
             (string-append "baz" letters end)))

     Here, anytime a line of FILE contains ‘hello’, it is replaced by
     ‘good morning’.  Anytime a line of FILE matches the second regexp,
     ‘all’ is bound to the complete match, ‘letters’ is bound to the
     first sub-expression, and ‘end’ is bound to the last one.

     When one of the MATCH-VAR is ‘_’, no variable is bound to the
     corresponding match substring.

     Alternatively, FILE may be a list of file names, in which case they
     are all subject to the substitutions.

     Be careful about using ‘$’ to match the end of a line; by itself it
     won’t match the terminating newline of a line.  For example, to
     match a whole line ending with a backslash, one needs a regex like
     ‘"(.*)\\\\\n$"’.

8.7.4 File Search
-----------------

This section documents procedures to search and filter files.

 -- Procedure: file-name-predicate regexp
     Return a predicate that returns true when passed a file name whose
     base name matches REGEXP.

 -- Procedure: find-files dir [pred] [#:stat lstat] [#:directories? #f]
          [#:fail-on-error? #f]
     Return the lexicographically sorted list of files under DIR for
     which PRED returns true.  PRED is passed two arguments: the
     absolute file name, and its stat buffer; the default predicate
     always returns true.  PRED can also be a regular expression, in
     which case it is equivalent to ‘(file-name-predicate PRED)’.  STAT
     is used to obtain file information; using ‘lstat’ means that
     symlinks are not followed.  If DIRECTORIES? is true, then
     directories will also be included.  If FAIL-ON-ERROR? is true,
     raise an exception upon error.

   Here are a few examples where we assume that the current directory is
the root of the Guix source tree:

     ;; List all the regular files in the current directory.
     (find-files ".")
     ⇒ ("./.dir-locals.el" "./.gitignore" ...)

     ;; List all the .scm files under gnu/services.
     (find-files "gnu/services" "\\.scm$")
     ⇒ ("gnu/services/admin.scm" "gnu/services/audio.scm" ...)

     ;; List ar files in the current directory.
     (find-files "." (lambda (file stat) (ar-file? file)))
     ⇒ ("./libformat.a" "./libstore.a" ...)

 -- Procedure: which program
     Return the complete file name for PROGRAM as found in ‘$PATH’, or
     ‘#f’ if PROGRAM could not be found.

 -- Procedure: search-input-file inputs name
 -- Procedure: search-input-directory inputs name
     Return the complete file name for NAME as found in INPUTS;
     ‘search-input-file’ searches for a regular file and
     ‘search-input-directory’ searches for a directory.  If NAME could
     not be found, an exception is raised.

     Here, INPUTS must be an association list like ‘inputs’ and
     ‘native-inputs’ as available to build phases (*note Build
     Phases::).

   Here is a (simplified) example of how ‘search-input-file’ is used in
a build phase of the ‘wireguard-tools’ package:

     (add-after 'install 'wrap-wg-quick
       (lambda* (#:key inputs outputs #:allow-other-keys)
         (let ((coreutils (string-append (assoc-ref inputs "coreutils")
                                         "/bin")))
           (wrap-program (search-input-file outputs "bin/wg-quick")
             #:sh (search-input-file inputs "bin/bash")
             `("PATH" ":" prefix ,(list coreutils))))))

8.7.5 Program Invocation
------------------------

You’ll find handy procedures to spawn processes in this module,
essentially convenient wrappers around Guile’s ‘system*’ (*note
‘system*’: (guile)Processes.).

 -- Procedure: invoke program args...
     Invoke PROGRAM with the given ARGS.  Raise an ‘&invoke-error’
     exception if the exit code is non-zero; otherwise return ‘#t’.

     The advantage compared to ‘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.

 -- Procedure: invoke-error? c
     Return true if C is an ‘&invoke-error’ condition.

 -- Procedure: invoke-error-program c
 -- Procedure: invoke-error-arguments c
 -- Procedure: invoke-error-exit-status c
 -- Procedure: invoke-error-term-signal c
 -- Procedure: invoke-error-stop-signal c
     Access specific fields of C, an ‘&invoke-error’ condition.

 -- Procedure: report-invoke-error c [port]
     Report to PORT (by default the current error port) about C, an
     ‘&invoke-error’ condition, in a human-friendly way.

     Typical usage would look like this:

          (use-modules (srfi srfi-34) ;for 'guard'
                       (guix build utils))

          (guard (c ((invoke-error? c)
                     (report-invoke-error c)))
            (invoke "date" "--imaginary-option"))

          ⊣ command "date" "--imaginary-option" failed with status 1

 -- Procedure: invoke/quiet program args...
     Invoke PROGRAM with ARGS and capture PROGRAM’s standard output and
     standard error.  If PROGRAM succeeds, print nothing and return the
     unspecified value; otherwise, raise a ‘&message’ error condition
     that includes the status code and the output of PROGRAM.

     Here’s an example:

          (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"))

          ⊣ 'date --imaginary-option' exited with status 1; output follows:

              date: unrecognized option '--imaginary-option'
              Try 'date --help' for more information.

8.7.6 Build Phases
------------------

The ‘(guix build utils)’ also contains tools to manipulate build phases
as used by build systems (*note Build Systems::).  Build phases are
represented as association lists or “alists” (*note (guile)Association
Lists::) where each key is a symbol naming the phase and the associated
value is a procedure (*note Build Phases::).

   Guile core and the ‘(srfi srfi-1)’ module both provide tools to
manipulate alists.  The ‘(guix build utils)’ module complements those
with tools written with build phases in mind.

 -- Macro: modify-phases phases clause...
     Modify PHASES sequentially as per each CLAUSE, which may have one
     of the following forms:

          (delete OLD-PHASE-NAME)
          (replace OLD-PHASE-NAME NEW-PHASE)
          (add-before OLD-PHASE-NAME NEW-PHASE-NAME NEW-PHASE)
          (add-after OLD-PHASE-NAME NEW-PHASE-NAME NEW-PHASE)

     Where every PHASE-NAME above is an expression evaluating to a
     symbol, and NEW-PHASE an expression evaluating to a procedure.

   The example below is taken from the definition of the ‘grep’ package.
It adds a phase to run after the ‘install’ phase, called
‘fix-egrep-and-fgrep’.  That phase is a procedure (‘lambda*’ is for
anonymous procedures) that takes a ‘#:outputs’ keyword argument and
ignores extra keyword arguments (*note (guile)Optional Arguments::, for
more on ‘lambda*’ and optional and keyword arguments.)  The phase uses
‘substitute*’ to modify the installed ‘egrep’ and ‘fgrep’ scripts so
that they refer to ‘grep’ by its absolute file name:

     (modify-phases %standard-phases
       (add-after 'install 'fix-egrep-and-fgrep
         ;; Patch 'egrep' and 'fgrep' to execute 'grep' via its
         ;; absolute file name instead of searching for it in $PATH.
         (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")))))))

   In the example below, phases are modified in two ways: the standard
‘configure’ phase is deleted, presumably because the package does not
have a ‘configure’ script or anything similar, and the default ‘install’
phase is replaced by one that manually copies the executable files to be
installed:

     (modify-phases %standard-phases
       (delete 'configure)      ;no 'configure' script
       (replace 'install
         (lambda* (#:key outputs #:allow-other-keys)
           ;; The package's Makefile doesn't provide an "install"
           ;; rule so do it by ourselves.
           (let ((bin (string-append (assoc-ref outputs "out")
                                     "/bin")))
             (install-file "footswitch" bin)
             (install-file "scythe" bin)))))

8.7.7 Wrappers
--------------

It is not unusual for a command to require certain environment variables
to be set for proper functioning, typically search paths (*note Search
Paths::).  Failing to do that, the command might fail to find files or
other commands it relies on, or it might pick the “wrong” ones—depending
on the environment in which it runs.  Examples include:

   • a shell script that assumes all the commands it uses are in ‘PATH’;

   • a Guile program that assumes all its modules are in
     ‘GUILE_LOAD_PATH’ and ‘GUILE_LOAD_COMPILED_PATH’;

   • a Qt application that expects to find certain plugins in
     ‘QT_PLUGIN_PATH’.

   For a package writer, the goal is to make sure commands always work
the same rather than depend on some external settings.  One way to
achieve that is to “wrap” commands in a thin script that sets those
environment variables, thereby ensuring that those run-time dependencies
are always found.  The wrapper would be used to set ‘PATH’,
‘GUILE_LOAD_PATH’, or ‘QT_PLUGIN_PATH’ in the examples above.

   To ease that task, the ‘(guix build utils)’ module provides a couple
of helpers to wrap commands.

 -- Procedure: wrap-program program [#:sh sh] [#:rest variables]
     Make a wrapper for PROGRAM.  VARIABLES should look like this:

          '(VARIABLE DELIMITER POSITION LIST-OF-DIRECTORIES)

     where DELIMITER is optional.  ‘:’ will be used if DELIMITER is not
     given.

     For example, this call:

          (wrap-program "foo"
                        '("PATH" ":" = ("/gnu/.../bar/bin"))
                        '("CERT_PATH" suffix ("/gnu/.../baz/certs"
                                              "/qux/certs")))

     will copy ‘foo’ to ‘.foo-real’ and create the file ‘foo’ with the
     following contents:

          #!location/of/bin/bash
          export PATH="/gnu/.../bar/bin"
          export CERT_PATH="$CERT_PATH${CERT_PATH:+:}/gnu/.../baz/certs:/qux/certs"
          exec -a $0 location/of/.foo-real "$@"

     If PROGRAM has previously been wrapped by ‘wrap-program’, the
     wrapper is extended with definitions for VARIABLES.  If it is not,
     SH will be used as the interpreter.

 -- Procedure: wrap-script program [#:guile guile] [#:rest variables]
     Wrap the script PROGRAM such that VARIABLES are set first.  The
     format of VARIABLES is the same as in the ‘wrap-program’ procedure.
     This procedure differs from ‘wrap-program’ in that it does not
     create a separate shell script.  Instead, PROGRAM is modified
     directly by prepending a Guile script, which is interpreted as a
     comment in the script’s language.

     Special encoding comments as supported by Python are recreated on
     the second line.

     Note that this procedure can only be used once per file as Guile
     scripts are not supported.


File: guix.info,  Node: Search Paths,  Next: The Store,  Prev: Build Utilities,  Up: Programming Interface

8.8 Search Paths
================

Many programs and libraries look for input data in a “search path”, a
list of directories: shells like Bash look for executables in the
command search path, a C compiler looks for ‘.h’ files in its header
search path, the Python interpreter looks for ‘.py’ files in its search
path, the spell checker has a search path for dictionaries, and so on.

   Search paths can usually be defined or overridden via environment
variables (*note (libc)Environment Variables::).  For example, the
search paths mentioned above can be changed by defining the ‘PATH’,
‘C_INCLUDE_PATH’, ‘PYTHONPATH’ (or ‘GUIX_PYTHONPATH’), and ‘DICPATH’
environment variables—you know, all these something-PATH variables that
you need to get right or things “won’t be found”.

   You may have noticed from the command line that Guix “knows” which
search path environment variables should be defined, and how.  When you
install packages in your default profile, the file
‘~/.guix-profile/etc/profile’ is created, which you can “source” from
the shell to set those variables.  Likewise, if you ask ‘guix shell’ to
create an environment containing Python and NumPy, a Python library, and
if you pass it the ‘--search-paths’ option, it will tell you about
‘PATH’ and ‘GUIX_PYTHONPATH’ (*note Invoking guix shell::):

     $ guix shell python python-numpy --pure --search-paths
     export PATH="/gnu/store/...-profile/bin"
     export GUIX_PYTHONPATH="/gnu/store/...-profile/lib/python3.9/site-packages"

   When you omit ‘--search-paths’, it defines these environment
variables right away, such that Python can readily find NumPy:

     $ guix shell python python-numpy -- python3
     Python 3.9.6 (default, Jan  1 1970, 00:00:01)
     [GCC 10.3.0] on linux
     Type "help", "copyright", "credits" or "license" for more information.
     >>> import numpy
     >>> numpy.version.version
     '1.20.3'

   For this to work, the definition of the ‘python’ package _declares_
the search path it cares about and its associated environment variable,
‘GUIX_PYTHONPATH’.  It looks like this:

     (package
       (name "python")
       (version "3.9.9")
       ;; some fields omitted...
       (native-search-paths
        (list (search-path-specification
               (variable "GUIX_PYTHONPATH")
               (files (list "lib/python/3.9/site-packages"))))))

   What this ‘native-search-paths’ field says is that, when the ‘python’
package is used, the ‘GUIX_PYTHONPATH’ environment variable must be
defined to include all the ‘lib/python/3.9/site-packages’
sub-directories encountered in its environment.  (The ‘native-’ bit
means that, if we are in a cross-compilation environment, only native
inputs may be added to the search path; *note ‘search-paths’: package
Reference.)  In the NumPy example above, the profile where ‘python’
appears contains exactly one such sub-directory, and ‘GUIX_PYTHONPATH’
is set to that.  When there are several
‘lib/python/3.9/site-packages’—this is the case in package build
environments—they are all added to ‘GUIX_PYTHONPATH’, separated by
colons (‘:’).

     Note: Notice that ‘GUIX_PYTHONPATH’ is specified as part of the
     definition of the ‘python’ package, and _not_ as part of that of
     ‘python-numpy’.  This is because this environment variable
     “belongs” to Python, not NumPy: Python actually reads the value of
     that variable and honors it.

     Corollary: if you create a profile that does not contain ‘python’,
     ‘GUIX_PYTHONPATH’ will _not_ be defined, even if it contains
     packages that provide ‘.py’ files:

          $ guix shell python-numpy --search-paths --pure
          export PATH="/gnu/store/...-profile/bin"

     This makes a lot of sense if we look at this profile in isolation:
     no software in this profile would read ‘GUIX_PYTHONPATH’.

   Of course, there are many variations on that theme: some packages
honor more than one search path, some use separators other than colon,
some accumulate several directories in their search path, and so on.  A
more complex example is the search path of libxml2: the value of the
‘XML_CATALOG_FILES’ environment variable is space-separated, it must
contain a list of ‘catalog.xml’ files (not directories), which are to be
found in ‘xml’ sub-directories—nothing less.  The search path
specification looks like this:

     (search-path-specification
      (variable "XML_CATALOG_FILES")
      (separator " ")
      (files '("xml"))
      (file-pattern "^catalog\\.xml$")
      (file-type 'regular))

   Worry not, search path specifications are usually not this tricky.

   The ‘(guix search-paths)’ module defines the data type of search path
specifications and a number of helper procedures.  Below is the
reference of search path specifications.

 -- Data Type: search-path-specification
     The data type for search path specifications.

     ‘variable’
          The name of the environment variable for this search path (a
          string).

     ‘files’
          The list of sub-directories (strings) that should be added to
          the search path.

     ‘separator’ (default: ‘":"’)
          The string used to separate search path components.

          As a special case, a ‘separator’ value of ‘#f’ specifies a
          “single-component search path”—in other words, a search path
          that cannot contain more than one element.  This is useful in
          some cases, such as the ‘SSL_CERT_DIR’ variable (honored by
          OpenSSL, cURL, and a few other packages) or the
          ‘ASPELL_DICT_DIR’ variable (honored by the GNU Aspell spell
          checker), both of which must point to a single directory.

     ‘file-type’ (default: ‘'directory’)
          The type of file being matched—‘'directory’ or ‘'regular’,
          though it can be any symbol returned by ‘stat:type’ (*note
          ‘stat’: (guile)File System.).

          In the ‘XML_CATALOG_FILES’ example above, we would match
          regular files; in the Python example, we would match
          directories.

     ‘file-pattern’ (default: ‘#f’)
          This must be either ‘#f’ or a regular expression specifying
          files to be matched _within_ the sub-directories specified by
          the ‘files’ field.

          Again, the ‘XML_CATALOG_FILES’ example shows a situation where
          this is needed.

   Some search paths are not tied by a single package but to many
packages.  To reduce duplications, some of them are pre-defined in
‘(guix search-paths)’.

 -- Variable: $SGML_CATALOG_FILES
 -- Variable: $XML_CATALOG_FILES
     These two search paths indicate where the TR9401 catalog
     (https://www.oasis-open.org/specs/a401.htm)(1) or XML catalog
     (https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html)
     files can be found.

 -- Variable: $SSL_CERT_DIR
 -- Variable: $SSL_CERT_FILE
     These two search paths indicate where X.509 certificates can be
     found (*note X.509 Certificates::).

   These pre-defined search paths can be used as in the following
example:

     (package
       (name "curl")
       ;; some fields omitted ...
       (native-search-paths (list $SSL_CERT_DIR $SSL_CERT_FILE)))

   How do you turn search path specifications on one hand and a bunch of
directories on the other hand in a set of environment variable
definitions?  That’s the job of ‘evaluate-search-paths’.

 -- Procedure: evaluate-search-paths search-paths directories [getenv]
     Evaluate SEARCH-PATHS, a list of search-path specifications, for
     DIRECTORIES, a list of directory names, and return a list of
     specification/value pairs.  Use GETENV to determine the current
     settings and report only settings not already effective.

   The ‘(guix profiles)’ provides a higher-level helper procedure,
‘load-profile’, that sets the environment variables of a profile.

   ---------- Footnotes ----------

   (1) Alternatively known as SGML catalog.


File: guix.info,  Node: The Store,  Next: Derivations,  Prev: Search Paths,  Up: Programming Interface

8.9 The Store
=============

Conceptually, the “store” is the place where derivations that have been
built successfully are stored—by default, ‘/gnu/store’.  Sub-directories
in the store are referred to as “store items” or sometimes “store
paths”.  The store has an associated database that contains information
such as the store paths referred to by each store path, and the list of
_valid_ store items—results of successful builds.  This database resides
in ‘LOCALSTATEDIR/guix/db’, where LOCALSTATEDIR is the state directory
specified via ‘--localstatedir’ at configure time, usually ‘/var’.

   The store is _always_ accessed by the daemon on behalf of its clients
(*note Invoking guix-daemon::).  To manipulate the store, clients
connect to the daemon over a Unix-domain socket, send requests to it,
and read the result—these are remote procedure calls, or RPCs.

     Note: Users must _never_ modify files under ‘/gnu/store’ directly.
     This would lead to inconsistencies and break the immutability
     assumptions of Guix’s functional model (*note Introduction::).

     *Note ‘guix gc --verify’: Invoking guix gc, for information on how
     to check the integrity of the store and attempt recovery from
     accidental modifications.

   The ‘(guix store)’ module provides procedures to connect to the
daemon, and to perform RPCs.  These are described below.  By default,
‘open-connection’, and thus all the ‘guix’ commands, connect to the
local daemon or to the URI specified by the ‘GUIX_DAEMON_SOCKET’
environment variable.

 -- Environment Variable: GUIX_DAEMON_SOCKET
     When set, the value of this variable should be a file name or a URI
     designating the daemon endpoint.  When it is a file name, it
     denotes a Unix-domain socket to connect to.  In addition to file
     names, the supported URI schemes are:

     ‘file’
     ‘unix’
          These are for Unix-domain sockets.
          ‘file:///var/guix/daemon-socket/socket’ is equivalent to
          ‘/var/guix/daemon-socket/socket’.

     ‘guix’
          These URIs denote connections over TCP/IP, without encryption
          nor authentication of the remote host.  The URI must specify
          the host name and optionally a port number (by default port
          44146 is used):

               guix://master.guix.example.org:1234

          This setup is suitable on local networks, such as clusters,
          where only trusted nodes may connect to the build daemon at
          ‘master.guix.example.org’.

          The ‘--listen’ option of ‘guix-daemon’ can be used to instruct
          it to listen for TCP connections (*note ‘--listen’: Invoking
          guix-daemon.).

     ‘ssh’
          These URIs allow you to connect to a remote daemon over SSH.
          This feature requires Guile-SSH (*note Requirements::) and a
          working ‘guile’ binary in ‘PATH’ on the destination machine.
          It supports public key and GSSAPI authentication.  A typical
          URL might look like this:

               ssh://charlie@guix.example.org:22

          As for ‘guix copy’, the usual OpenSSH client configuration
          files are honored (*note Invoking guix copy::).

     Additional URI schemes may be supported in the future.

          Note: The ability to connect to remote build daemons is
          considered experimental as of 1.5.0.  Please get in touch with
          us to share any problems or suggestions you may have (*note
          Contributing::).

 -- Procedure: open-connection [uri] [#:reserve-space? #t]
     Connect to the daemon over the Unix-domain socket at URI (a
     string).  When RESERVE-SPACE? is true, instruct it to reserve a
     little bit of extra space on the file system so that the garbage
     collector can still operate should the disk become full.  Return a
     server object.

     FILE defaults to ‘%default-socket-path’, which is the normal
     location given the options that were passed to ‘configure’.

 -- Procedure: close-connection server
     Close the connection to SERVER.

 -- Variable: current-build-output-port
     This variable is bound to a SRFI-39 parameter, which refers to the
     port where build and error logs sent by the daemon should be
     written.

   Procedures that make RPCs all take a server object as their first
argument.

 -- Procedure: valid-path? server path
     Return ‘#t’ when PATH designates a valid store item and ‘#f’
     otherwise (an invalid item may exist on disk but still be invalid,
     for instance because it is the result of an aborted or failed
     build).

     A ‘&store-protocol-error’ condition is raised if PATH is not
     prefixed by the store directory (‘/gnu/store’).

 -- Procedure: add-text-to-store server name text [references]
     Add TEXT under file NAME in the store, and return its store path.
     REFERENCES is the list of store paths referred to by the resulting
     store path.

 -- Procedure: build-derivations store derivations [mode]
     Build DERIVATIONS, a list of ‘<derivation>’ objects, ‘.drv’ file
     names, or derivation/output pairs, using the specified
     MODE—‘(build-mode normal)’ by default.

   Note that the ‘(guix monads)’ module provides a monad as well as
monadic versions of the above procedures, with the goal of making it
more convenient to work with code that accesses the store (*note The
Store Monad::).

   This section is currently incomplete.


File: guix.info,  Node: Derivations,  Next: The Store Monad,  Prev: The Store,  Up: Programming Interface

8.10 Derivations
================

Low-level build actions and the environment in which they are performed
are represented by “derivations”.  A derivation contains the following
pieces of information:

   • The outputs of the derivation—derivations produce at least one file
     or directory in the store, but may produce more.

   • The inputs of the derivation—i.e., its build-time
     dependencies—which may be other derivations or plain files in the
     store (patches, build scripts, etc.).

   • The system type targeted by the derivation—e.g., ‘x86_64-linux’.

   • The file name of a build script in the store, along with the
     arguments to be passed.

   • A list of environment variables to be defined.

   Derivations allow clients of the daemon to communicate build actions
to the store.  They exist in two forms: as an in-memory representation,
both on the client- and daemon-side, and as files in the store whose
name end in ‘.drv’—these files are referred to as “derivation paths”.
Derivations paths can be passed to the ‘build-derivations’ procedure to
perform the build actions they prescribe (*note The Store::).

   Operations such as file downloads and version-control checkouts for
which the expected content hash is known in advance are modeled as
“fixed-output derivations”.  Unlike regular derivations, the outputs of
a fixed-output derivation are independent of its inputs—e.g., a source
code download produces the same result regardless of the download method
and tools being used.

   The outputs of derivations—i.e., the build results—have a set of
“references”, as reported by the ‘references’ RPC or the ‘guix gc
--references’ command (*note Invoking guix gc::).  References are the
set of run-time dependencies of the build results.  References are a
subset of the inputs of the derivation; this subset is automatically
computed by the build daemon by scanning all the files in the outputs.

   The ‘(guix derivations)’ module provides a representation of
derivations as Scheme objects, along with procedures to create and
otherwise manipulate derivations.  The lowest-level primitive to create
a derivation is the ‘derivation’ procedure:

 -- Procedure: derivation store name builder args [#:outputs '("out")]
          [#:hash #f] [#:hash-algo #f] [#:recursive? #f] [#:inputs '()]
          [#:env-vars '()] [#:system (%current-system)]
          [#:references-graphs #f] [#:allowed-references #f]
          [#:disallowed-references #f] [#:leaked-env-vars #f]
          [#:local-build? #f] [#:substitutable? #t] [#:properties '()]
     Build a derivation with the given arguments, and return the
     resulting ‘<derivation>’ object.

     When HASH and HASH-ALGO are given, a “fixed-output derivation” is
     created—i.e., one whose result is known in advance, such as a file
     download.  If, in addition, RECURSIVE? is true, then that fixed
     output may be an executable file or a directory and HASH must be
     the hash of an archive containing this output.

     When REFERENCES-GRAPHS is true, it must be a list of file
     name/store path pairs.  In that case, the reference graph of each
     store path is exported in the build environment in the
     corresponding file, in a simple text format.

     When ALLOWED-REFERENCES is true, it must be a list of store items
     or outputs that the derivation’s output may refer to.  Likewise,
     DISALLOWED-REFERENCES, if true, must be a list of things the
     outputs may _not_ refer to.

     When LEAKED-ENV-VARS is true, it must be a list of strings denoting
     environment variables that are allowed to “leak” from the daemon’s
     environment to the build environment.  This is only applicable to
     fixed-output derivations—i.e., when HASH is true.  The main use is
     to allow variables such as ‘http_proxy’ to be passed to derivations
     that download files.

     When LOCAL-BUILD? is true, declare that the derivation is not a
     good candidate for offloading and should rather be built locally
     (*note Daemon Offload Setup::).  This is the case for small
     derivations where the costs of data transfers would outweigh the
     benefits.

     When SUBSTITUTABLE? is false, declare that substitutes of the
     derivation’s output should not be used (*note Substitutes::).  This
     is useful, for instance, when building packages that capture
     details of the host CPU instruction set.

     PROPERTIES must be an association list describing “properties” of
     the derivation.  It is kept as-is, uninterpreted, in the
     derivation.

Here’s an example with a shell script as its builder, assuming STORE is
an open connection to the daemon, and BASH points to a Bash executable
in the store:

     (use-modules (guix utils)
                  (guix store)
                  (guix derivations))

     (let ((builder   ; add the Bash script to the store
             (add-text-to-store store "my-builder.sh"
                                "echo hello world > $out\n" '())))
       (derivation store "foo"
                   bash `("-e" ,builder)
                   #:inputs `((,bash) (,builder))
                   #:env-vars '(("HOME" . "/homeless"))))
     ⇒ #<derivation /gnu/store/...-foo.drv => /gnu/store/...-foo>

   As can be guessed, this primitive is cumbersome to use directly.  A
better approach is to write build scripts in Scheme, of course!  The
best course of action for that is to write the build code as a
“G-expression”, and to pass it to ‘gexp->derivation’.  For more
information, *note G-Expressions::.

   Once upon a time, ‘gexp->derivation’ did not exist and constructing
derivations with build code written in Scheme was achieved with
‘build-expression->derivation’, documented below.  This procedure is now
deprecated in favor of the much nicer ‘gexp->derivation’.

 -- Procedure: build-expression->derivation store name exp [#:system
          (%current-system)] [#:inputs '()] [#:outputs '("out")] [#:hash
          #f] [#:hash-algo #f] [#:recursive? #f] [#:env-vars '()]
          [#:modules '()] [#:references-graphs #f] [#:allowed-references
          #f] [#:disallowed-references #f] [#:local-build? #f]
          [#:substitutable? #t] [#:guile-for-build #f]
     Return a derivation that executes Scheme expression EXP as a
     builder for derivation NAME.  INPUTS must be a list of ‘(name
     drv-path sub-drv)’ tuples; when SUB-DRV is omitted, ‘"out"’ is
     assumed.  MODULES is a list of names of Guile modules from the
     current search path to be copied in the store, compiled, and made
     available in the load path during the execution of EXP—e.g.,
     ‘((guix build utils) (guix build gnu-build-system))’.

     EXP is evaluated in an environment where ‘%outputs’ is bound to a
     list of output/path pairs, and where ‘%build-inputs’ is bound to a
     list of string/output-path pairs made from INPUTS.  Optionally,
     ENV-VARS is a list of string pairs specifying the name and value of
     environment variables visible to the builder.  The builder
     terminates by passing the result of EXP to ‘exit’; thus, when EXP
     returns ‘#f’, the build is considered to have failed.

     EXP is built using GUILE-FOR-BUILD (a derivation).  When
     GUILE-FOR-BUILD is omitted or is ‘#f’, the value of the
     ‘%guile-for-build’ fluid is used instead.

     See the ‘derivation’ procedure for the meaning of
     REFERENCES-GRAPHS, ALLOWED-REFERENCES, DISALLOWED-REFERENCES,
     LOCAL-BUILD?, and SUBSTITUTABLE?.

Here’s an example of a single-output derivation that creates a directory
containing one file:

     (let ((builder '(let ((out (assoc-ref %outputs "out")))
                       (mkdir out)    ; create /gnu/store/...-goo
                       (call-with-output-file (string-append out "/test")
                         (lambda (p)
                           (display '(hello guix) p))))))
       (build-expression->derivation store "goo" builder))

     ⇒ #<derivation /gnu/store/...-goo.drv => ...>


File: guix.info,  Node: The Store Monad,  Next: G-Expressions,  Prev: Derivations,  Up: Programming Interface

8.11 The Store Monad
====================

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 include 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 “monadic procedures”.

   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))))

   Using ‘(guix monads)’ and ‘(guix gexp)’, it may be rewritten as a
monadic function:

     (define (sh-symlink)
       ;; Same, but return a monadic value.
       (mlet %store-monad ((drv (package->derivation bash)))
         (gexp->derivation "sh"
                           #~(symlink (string-append #$drv "/bin/bash")
                                      #$output))))

   There are several things to note in the second version: the ‘store’
parameter is now implicit and is “threaded” in the calls to the
‘package->derivation’ and ‘gexp->derivation’ monadic procedures, and the
monadic value returned by ‘package->derivation’ is “bound” using ‘mlet’
instead of plain ‘let’.

   As it turns out, the call to ‘package->derivation’ can even be
omitted since it will take place implicitly, as we will see later (*note
G-Expressions::):

     (define (sh-symlink)
       (gexp->derivation "sh"
                         #~(symlink (string-append #$bash "/bin/bash")
                                    #$output)))

   Calling the monadic ‘sh-symlink’ has no effect.  As someone once
said, “you exit a monad like you exit a building on fire: by running”.
So, to exit the monad and get the desired effect, one must use
‘run-with-store’:

     (run-with-store (open-connection) (sh-symlink))
     ⇒ /gnu/store/...-sh-symlink

   Note that the ‘(guix monad-repl)’ module extends the Guile REPL with
new “commands” to make it easier to deal with monadic procedures:
‘run-in-store’, and ‘enter-store-monad’ (*note Using Guix
Interactively::).  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) [1]> (package->derivation hello)
     $2 = #<derivation /gnu/store/...-hello-2.9.drv => ...>
     store-monad@(guile-user) [1]> (text-file "foo" "Hello!")
     $3 = "/gnu/store/...-foo"
     store-monad@(guile-user) [1]> ,q
     scheme@(guile-user)>

Note that non-monadic values cannot be returned in the ‘store-monad’
REPL.

   Other meta-commands are available at the REPL, such as ‘,build’ to
build a file-like object (*note Using Guix Interactively::).

   The main syntactic forms to deal with monads in general are provided
by the ‘(guix monads)’ module and are described below.

 -- Macro: with-monad monad body ...
     Evaluate any ‘>>=’ or ‘return’ forms in BODY as being in MONAD.

 -- Macro: return val
     Return a monadic value that encapsulates VAL.

 -- Macro: >>= mval mproc ...
     “Bind” monadic value MVAL, passing its “contents” to monadic
     procedures MPROC...(1).  There can be one MPROC or several of them,
     as in this example:

          (run-with-state
              (with-monad %state-monad
                (>>= (return 1)
                     (lambda (x) (return (+ 1 x)))
                     (lambda (x) (return (* 2 x)))))
            'some-state)

          ⇒ 4
          ⇒ some-state

 -- Macro: mlet monad ((var mval) ...) body ...
 -- Macro: mlet* monad ((var mval) ...) body ...
     Bind the variables VAR to the monadic values MVAL in BODY, which is
     a sequence of expressions.  As with the bind operator, this can be
     thought of as “unpacking” the raw, non-monadic value “contained” in
     MVAL and making VAR refer to that raw, non-monadic value within the
     scope of the BODY.  The form (VAR -> VAL) binds VAR to the “normal”
     value VAL, as per ‘let’.  The binding operations occur in sequence
     from left to right.  The last expression of BODY must be a monadic
     expression, and its result will become the result of the ‘mlet’ or
     ‘mlet*’ when run in the MONAD.

     ‘mlet*’ is to ‘mlet’ what ‘let*’ is to ‘let’ (*note (guile)Local
     Bindings::).

 -- Macro: mbegin monad mexp ...
     Bind MEXP and the following monadic expressions in sequence,
     returning the result of the last expression.  Every expression in
     the sequence must be a monadic 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.

 -- Macro: mwhen condition mexp0 mexp* ...
     When CONDITION is true, evaluate the sequence of monadic
     expressions MEXP0..MEXP* as in an ‘mbegin’.  When CONDITION is
     false, return ‘*unspecified*’ in the current monad.  Every
     expression in the sequence must be a monadic expression.

 -- Macro: munless condition mexp0 mexp* ...
     When CONDITION is false, evaluate the sequence of monadic
     expressions MEXP0..MEXP* as in an ‘mbegin’.  When CONDITION is
     true, return ‘*unspecified*’ in the current monad.  Every
     expression in the sequence must be a monadic expression.

   The ‘(guix monads)’ module provides the “state monad”, which allows
an additional value—the state—to be _threaded_ through monadic procedure
calls.

 -- Variable: %state-monad
     The state monad.  Procedures in the state monad can access and
     change the state that is threaded.

     Consider the example below.  The ‘square’ procedure returns a value
     in the state monad.  It returns the square of its argument, but
     also increments the current state value:

          (define (square x)
            (mlet %state-monad ((count (current-state)))
              (mbegin %state-monad
                (set-current-state (+ 1 count))
                (return (* x x)))))

          (run-with-state (sequence %state-monad (map square (iota 3))) 0)
          ⇒ (0 1 4)
          ⇒ 3

     When “run” through ‘%state-monad’, we obtain that additional state
     value, which is the number of ‘square’ calls.

 -- Monadic Procedure: current-state
     Return the current state as a monadic value.

 -- Monadic Procedure: set-current-state VALUE
     Set the current state to VALUE and return the previous state as a
     monadic value.

 -- Monadic Procedure: state-push VALUE
     Push VALUE to the current state, which is assumed to be a list, and
     return the previous state as a monadic value.

 -- Monadic Procedure: state-pop
     Pop a value from the current state and return it as a monadic
     value.  The state is assumed to be a list.

 -- Procedure: run-with-state mval [state]
     Run monadic value MVAL starting with STATE as the initial state.
     Return two values: the resulting value, and the resulting state.

   The main interface to the store monad, provided by the ‘(guix store)’
module, is as follows.

 -- Variable: %store-monad
     The store monad—an alias for ‘%state-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
     below).

 -- Procedure: run-with-store store mval [#:guile-for-build] [#:system
          (%current-system)]
     Run MVAL, a monadic value in the store monad, in STORE, an open
     store connection.

 -- Monadic Procedure: text-file NAME TEXT [REFERENCES]
     Return as a monadic value the absolute file name in the store of
     the file containing TEXT, a string.  REFERENCES is a list of store
     items that the resulting text file refers to; it defaults to the
     empty list.

 -- Monadic Procedure: binary-file NAME DATA [REFERENCES]
     Return as a monadic value the absolute file name in the store of
     the file containing DATA, a bytevector.  REFERENCES is a list of
     store items that the resulting binary file refers to; it defaults
     to the empty list.

 -- Monadic Procedure: interned-file FILE [NAME] [#:recursive? #t]
          [#:select? (const #t)]
     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.

     When RECURSIVE? is true, call ‘(SELECT? FILE STAT)’ for each
     directory entry, where FILE is the entry’s absolute file name and
     STAT is the result of ‘lstat’; exclude entries for which SELECT?
     does not return true.

     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")

   The ‘(guix packages)’ module exports the following package-related
monadic procedures:

 -- Monadic Procedure: package-file PACKAGE [FILE] [#:system
          (%current-system)] [#:target #f] [#:output "out"]
     Return as a monadic 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.

     Note that this procedure does _not_ build PACKAGE.  Thus, the
     result might or might not designate an existing file.  We recommend
     not using this procedure unless you know what you are doing.

 -- Monadic Procedure: package->derivation PACKAGE [SYSTEM]
 -- Monadic Procedure: package->cross-derivation PACKAGE TARGET [SYSTEM]
     Monadic version of ‘package-derivation’ and
     ‘package-cross-derivation’ (*note Defining Packages::).

   ---------- Footnotes ----------

   (1) 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.


File: guix.info,  Node: G-Expressions,  Next: Invoking guix repl,  Prev: The Store Monad,  Up: Programming Interface

8.12 G-Expressions
==================

So we have “derivations”, which represent a sequence of build actions to
be performed to produce an item in the store (*note Derivations::).
These build actions are performed when asking the daemon to actually
build the derivations; they are run by the daemon in a container (*note
Invoking guix-daemon::).

   It should come as no surprise that we like to write these build
actions in Scheme.  When we do that, we end up with two “strata” of
Scheme code(1): the “host code”—code that defines packages, talks to the
daemon, etc.—and the “build code”—code that actually performs build
actions, such as making directories, invoking ‘make’, and so on (*note
Build Phases::).

   To describe a derivation and its build actions, one typically needs
to embed build code inside host code.  It boils down to manipulating
build code as data, and the homoiconicity of Scheme—code has a direct
representation as data—comes in handy for that.  But we need more than
the normal ‘quasiquote’ mechanism in Scheme to construct build
expressions.

   The ‘(guix gexp)’ module implements “G-expressions”, a form of
S-expressions adapted to build expressions.  G-expressions, or “gexps”,
consist essentially of three syntactic forms: ‘gexp’, ‘ungexp’, and
‘ungexp-splicing’ (or simply: ‘#~’, ‘#$’, and ‘#$@’), which are
comparable to ‘quasiquote’, ‘unquote’, and ‘unquote-splicing’,
respectively (*note ‘quasiquote’: (guile)Expression Syntax.).  However,
there are major differences:

   • Gexps are meant to be written to a file and run or manipulated by
     other processes.

   • When a high-level object such as a package or derivation is
     unquoted inside a gexp, the result is as if its output file name
     had been introduced.

   • Gexps carry information about the packages or derivations they
     refer to, and these dependencies are automatically added as inputs
     to the build processes that use them.

   This mechanism is not limited to package and derivation objects:
“compilers” able to “lower” other high-level objects to derivations or
files in the store can be defined, such that these objects can also be
inserted into gexps.  For example, a useful type of high-level objects
that can be inserted in a gexp is “file-like objects”, which make it
easy to add files to the store and to refer to them in derivations and
such (see ‘local-file’ and ‘plain-file’ below).

   To illustrate the idea, here is an example of a gexp:

     (define build-exp
       #~(begin
           (mkdir #$output)
           (chdir #$output)
           (symlink (string-append #$coreutils "/bin/ls")
                    "list-files")))

   This gexp can be passed to ‘gexp->derivation’; we obtain a derivation
that builds a directory containing exactly one symlink to
‘/gnu/store/...-coreutils-8.22/bin/ls’:

     (gexp->derivation "the-thing" build-exp)

   As one would expect, the ‘"/gnu/store/...-coreutils-8.22"’ string is
substituted to the reference to the COREUTILS package in the actual
build code, and COREUTILS is automatically made an input to the
derivation.  Likewise, ‘#$output’ (equivalent to ‘(ungexp output)’) is
replaced by a string containing the directory name of the output of the
derivation.

   In a cross-compilation context, it is useful to distinguish between
references to the _native_ build of a package—that can run on the
host—versus references to cross builds of a package.  To that end, the
‘#+’ plays the same role as ‘#$’, but is a reference to a native package
build:

     (gexp->derivation "vi"
        #~(begin
            (mkdir #$output)
            (mkdir (string-append #$output "/bin"))
            (system* (string-append #+coreutils "/bin/ln")
                     "-s"
                     (string-append #$emacs "/bin/emacs")
                     (string-append #$output "/bin/vi")))
        #:target "aarch64-linux-gnu")

In the example above, the native build of COREUTILS is used, so that
‘ln’ can actually run on the host; but then the cross-compiled build of
EMACS is referenced.

   Another gexp feature is “imported modules”: sometimes you want to be
able to use certain Guile modules from the “host environment” in the
gexp, so those modules should be imported in the “build environment”.
The ‘with-imported-modules’ form allows you to express that:

     (let ((build (with-imported-modules '((guix build utils))
                    #~(begin
                        (use-modules (guix build utils))
                        (mkdir-p (string-append #$output "/bin"))))))
       (gexp->derivation "empty-dir"
                         #~(begin
                             #$build
                             (display "success!\n")
                             #t)))

In this example, the ‘(guix build utils)’ module is automatically pulled
into the isolated build environment of our gexp, such that ‘(use-modules
(guix build utils))’ works as expected.

   Usually you want the _closure_ of the module to be imported—i.e., the
module itself and all the modules it depends on—rather than just the
module; failing to do that, attempts to use the module will fail because
of missing dependent modules.  The ‘source-module-closure’ procedure
computes the closure of a module by looking at its source file headers,
which comes in handy in this case:

     (use-modules (guix modules))   ;for 'source-module-closure'

     (with-imported-modules (source-module-closure
                              '((guix build utils)
                                (gnu build image)))
       (gexp->derivation "something-with-vms"
                         #~(begin
                             (use-modules (guix build utils)
                                          (gnu build image))
                             ...)))

   In the same vein, sometimes you want to import not just pure-Scheme
modules, but also “extensions” such as Guile bindings to C libraries or
other “full-blown” packages.  Say you need the ‘guile-json’ package
available on the build side, here’s how you would do it:

     (use-modules (gnu packages guile))  ;for 'guile-json'

     (with-extensions (list guile-json)
       (gexp->derivation "something-with-json"
                         #~(begin
                             (use-modules (json))
                             ...)))

   The syntactic form to construct gexps is summarized below.

 -- Macro: #~EXP
 -- Macro: (gexp EXP)
     Return a G-expression containing EXP.  EXP may contain one or more
     of the following forms:

     ‘#$OBJ’
     ‘(ungexp OBJ)’
          Introduce a reference to OBJ.  OBJ may have one of the
          supported types, for example a package or a derivation, in
          which case the ‘ungexp’ form is replaced by its output file
          name—e.g., ‘"/gnu/store/...-coreutils-8.22’.

          If OBJ is a list, it is traversed and references to supported
          objects are substituted similarly.

          If OBJ is another gexp, its contents are inserted and its
          dependencies are added to those of the containing gexp.

          If OBJ is another kind of object, it is inserted as is.

     ‘#$OBJ:OUTPUT’
     ‘(ungexp OBJ OUTPUT)’
          This is like the form above, but referring explicitly to the
          OUTPUT of OBJ—this is useful when OBJ produces multiple
          outputs (*note Packages with Multiple Outputs::).

          Sometimes a gexp unconditionally refers to the ‘"out"’ output,
          but the user of that gexp would still like to insert a
          reference to another output.  The ‘gexp-input’ procedure aims
          to address that.  *Note gexp-input::.

     ‘#+OBJ’
     ‘#+OBJ:output’
     ‘(ungexp-native OBJ)’
     ‘(ungexp-native OBJ OUTPUT)’
          Same as ‘ungexp’, but produces a reference to the _native_
          build of OBJ when used in a cross compilation context.

     ‘#$output[:OUTPUT]’
     ‘(ungexp output [OUTPUT])’
          Insert a reference to derivation output OUTPUT, or to the main
          output when OUTPUT is omitted.

          This only makes sense for gexps passed to ‘gexp->derivation’.

     ‘#$@LST’
     ‘(ungexp-splicing LST)’
          Like the above, but splices the contents of LST inside the
          containing list.

     ‘#+@LST’
     ‘(ungexp-native-splicing LST)’
          Like the above, but refers to native builds of the objects
          listed in LST.

     G-expressions created by ‘gexp’ or ‘#~’ are run-time objects of the
     ‘gexp?’ type (see below).

 -- Macro: with-imported-modules modules body...
     Mark the gexps defined in BODY... as requiring MODULES in their
     execution environment.

     Each item in MODULES can be the name of a module, such as ‘(guix
     build utils)’, or it can be a module name, followed by an arrow,
     followed by a file-like object:

          `((guix build utils)
            (guix gcrypt)
            ((guix config) => ,(scheme-file "config.scm"
                                            #~(define-module ...))))

     In the example above, the first two modules are taken from the
     search path, and the last one is created from the given file-like
     object.

     This form has _lexical_ scope: it has an effect on the gexps
     directly defined in BODY..., but not on those defined, say, in
     procedures called from BODY....

 -- Macro: with-extensions extensions body...
     Mark the gexps defined in BODY... as requiring EXTENSIONS in their
     build and execution environment.  EXTENSIONS is typically a list of
     package objects such as those defined in the ‘(gnu packages guile)’
     module.

     Concretely, the packages listed in EXTENSIONS are added to the load
     path while compiling imported modules in BODY...; they are also
     added to the load path of the gexp returned by BODY....

 -- Procedure: gexp? obj
     Return ‘#t’ if OBJ is a G-expression.

   G-expressions are meant to be written to disk, either as code
building some derivation, or as plain files in the store.  The monadic
procedures below allow you to do that (*note The Store Monad::, for more
information about monads).

 -- Monadic Procedure: gexp->derivation NAME EXP [#:system
          (%current-system)] [#:target #f] [#:graft? #t] [#:hash #f]
          [#:hash-algo #f] [#:recursive? #f] [#:env-vars '()] [#:modules
          '()] [#:module-path %load-path] [#:effective-version "2.2"]
          [#:references-graphs #f] [#:allowed-references #f]
          [#:disallowed-references #f] [#:leaked-env-vars #f]
          [#:script-name (string-append NAME "-builder")]
          [#:deprecation-warnings #f] [#:local-build? #f]
          [#:substitutable? #t] [#:properties '()] [#:guile-for-build
          #f]
     Return a derivation NAME that runs EXP (a gexp) with
     GUILE-FOR-BUILD (a derivation) on SYSTEM; EXP is stored in a file
     called SCRIPT-NAME.  When TARGET is true, it is used as the
     cross-compilation target triplet for packages referred to by EXP.

     MODULES is deprecated in favor of ‘with-imported-modules’.  Its
     meaning is to make MODULES available in the evaluation context of
     EXP; MODULES is a list of names of Guile modules searched in
     MODULE-PATH to be copied in the store, compiled, and made available
     in the load path during the execution of EXP—e.g., ‘((guix build
     utils) (guix build gnu-build-system))’.

     EFFECTIVE-VERSION determines the string to use when adding
     extensions of EXP (see ‘with-extensions’) to the search path—e.g.,
     ‘"2.2"’.

     GRAFT? determines whether packages referred to by EXP should be
     grafted when applicable.

     When REFERENCES-GRAPHS is true, it must be a list of tuples of one
     of the following forms:

          (FILE-NAME OBJ)
          (FILE-NAME OBJ OUTPUT)
          (FILE-NAME GEXP-INPUT)
          (FILE-NAME STORE-ITEM)

     The right-hand-side of each element of REFERENCES-GRAPHS is
     automatically made an input of the build process of EXP.  In the
     build environment, each FILE-NAME contains the reference graph of
     the corresponding item, in a simple text format.

     ALLOWED-REFERENCES must be either ‘#f’ or a list of output names
     and packages.  In the latter case, the list denotes store items
     that the result is allowed to refer to.  Any reference to another
     store item will lead to a build error.  Similarly for
     DISALLOWED-REFERENCES, which can list items that must not be
     referenced by the outputs.

     DEPRECATION-WARNINGS determines whether to show deprecation
     warnings while compiling modules.  It can be ‘#f’, ‘#t’, or
     ‘'detailed’.

     The other arguments are as for ‘derivation’ (*note Derivations::).

   The ‘local-file’, ‘plain-file’, ‘computed-file’, ‘program-file’, and
‘scheme-file’ procedures below return “file-like objects”.  That is,
when unquoted in a G-expression, these objects lead to a file in the
store.  Consider this G-expression:

     #~(system* #$(file-append glibc "/sbin/nscd") "-f"
                #$(local-file "/tmp/my-nscd.conf"))

   The effect here is to “intern” ‘/tmp/my-nscd.conf’ by copying it to
the store.  Once expanded, for instance via ‘gexp->derivation’, the
G-expression refers to that copy under ‘/gnu/store’; thus, modifying or
removing the file in ‘/tmp’ does not have any effect on what the
G-expression does.  ‘plain-file’ can be used similarly; it differs in
that the file content is directly passed as a string.

 -- Procedure: local-file file [name] [#:recursive? #f] [#:select?
          (const #t)]
     Return an object representing local file FILE to add to the store;
     this object can be used in a gexp.  If FILE is a literal string
     denoting a relative file name, it is looked up relative to the
     source file where it appears; if FILE is not a literal string, it
     is looked up relative to the current working directory at run time.
     FILE will be added to the store under NAME–by default the base name
     of FILE.

     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.

     When RECURSIVE? is true, call ‘(SELECT? FILE STAT)’ for each
     directory entry, where FILE is the entry’s absolute file name and
     STAT is the result of ‘lstat’; exclude entries for which SELECT?
     does not return true.

     FILE can be wrapped in the ‘assume-valid-file-name’ syntactic
     keyword.  When this is done, there will not be a warning when
     ‘local-file’ is used with a non-literal path.  The path is still
     looked up relative to the current working directory at run time.
     Wrapping is done like this:

          (define alice-key-file-path "alice.pub")
          ;; ...
          (local-file (assume-valid-file-name alice-key-file-path))

     FILE can be wrapped in the ‘assume-source-relative-file-name’
     syntactic keyword.  When this is done, the file name will be looked
     up relative to the source file where it appears even when it is not
     a string literal.

     This is the declarative counterpart of the ‘interned-file’ monadic
     procedure (*note ‘interned-file’: The Store Monad.).

 -- Procedure: plain-file name content
     Return an object representing a text file called NAME with the
     given CONTENT (a string or a bytevector) to be added to the store.

     This is the declarative counterpart of ‘text-file’.

 -- Procedure: computed-file NAME GEXP [#:guile] [#:local-build? #t]
          [#:options '()]
     Return an object representing the store item NAME, a file or
     directory computed by GEXP.  When LOCAL-BUILD? is true (the
     default), the derivation is built locally.  OPTIONS is a list of
     additional arguments to pass to ‘gexp->derivation’.

     This is the declarative counterpart of ‘gexp->derivation’.

 -- Monadic Procedure: gexp->script NAME EXP [#:guile (default-guile)]
          [#:module-path %load-path] [#:system (%current-system)]
          [#:target 'current]
     Return an executable script NAME that runs EXP using GUILE, with
     EXP’s imported modules in its search path.  Look up EXP’s modules
     in MODULE-PATH.

     The example below builds a script that simply invokes the ‘ls’
     command:

          (use-modules (guix gexp) (gnu packages base))

          (gexp->script "list-files"
                        #~(execl #$(file-append coreutils "/bin/ls")
                                 "ls"))

     When “running” it through the store (*note ‘run-with-store’: The
     Store Monad.), we obtain a derivation that produces an executable
     file ‘/gnu/store/...-list-files’ along these lines:

          #!/gnu/store/...-guile-2.0.11/bin/guile -ds
          !#
          (execl "/gnu/store/...-coreutils-8.22"/bin/ls" "ls")

 -- Procedure: program-file name exp [#:guile #f] [#:module-path
          %load-path]
     Return an object representing the executable store item NAME that
     runs GEXP.  GUILE is the Guile package used to execute that script.
     Imported modules of GEXP are looked up in MODULE-PATH.

     This is the declarative counterpart of ‘gexp->script’.

 -- Monadic Procedure: gexp->file NAME EXP [#:set-load-path? #t]
          [#:module-path %load-path] [#:splice? #f] [#:guile
          (default-guile)] [#:system (%current-system)] [#:target
          'current]
     Return a derivation that builds a file NAME containing EXP.  When
     SPLICE? is true, EXP is considered to be a list of expressions that
     will be spliced in the resulting file.

     When SET-LOAD-PATH? is true, emit code in the resulting file to set
     ‘%load-path’ and ‘%load-compiled-path’ to honor EXP’s imported
     modules.  Look up EXP’s modules in MODULE-PATH.

     The resulting file holds references to all the dependencies of EXP
     or a subset thereof.

 -- Procedure: scheme-file name exp [#:splice? #f] [#:guile #f]
          [#:set-load-path? #t]
     Return an object representing the Scheme file NAME that contains
     EXP.  GUILE is the Guile package used to produce that file.

     This is the declarative counterpart of ‘gexp->file’.

 -- Monadic Procedure: text-file* NAME TEXT ...
     Return as a monadic value a derivation that builds a text file
     containing all of TEXT.  TEXT may list, in addition to strings,
     objects of any type that can be used in a gexp: packages,
     derivations, local file objects, etc.  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, like this:

          (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 reference COREUTILS, GREP, and SED, thereby preventing them
     from being garbage-collected during its lifetime.

 -- Procedure: mixed-text-file name text ...
     Return an object representing store file NAME containing TEXT.
     TEXT is a sequence of strings and file-like objects, as in:

          (mixed-text-file "profile"
                           "export PATH=" coreutils "/bin:" grep "/bin")

     This is the declarative counterpart of ‘text-file*’.

 -- Procedure: file-union name files [#:dangling-symlinks? #f]
     Return a ‘<computed-file>’ that builds a directory containing all
     of FILES.  Each item in FILES must be a two-element list where the
     first element is the file name to use in the new directory, and the
     second element is a gexp denoting the target file.
     ‘#:dangling-symlinks?’ controls if gexps must lower to an existing
     file.  Here’s an example:

          (file-union "etc"
                      `(("hosts" ,(plain-file "hosts"
                                              "127.0.0.1 localhost"))
                        ("bashrc" ,(plain-file "bashrc"
                                               "alias ls='ls --color=auto'"))))

     This yields an ‘etc’ directory containing these two files.

 -- Procedure: symlink-to target
     Return a ‘<computed-file>’ that is a symbolic link to target.
     Note, that the target does not need to exist at the build time.
     One of uses is to put arbitrary symlinks into user’s home:

          (service home-files-service-type
            `(("Sync" ,(symlink-to "/storage/Sync"))))

 -- Procedure: directory-union name things
     Return a directory that is the union of THINGS, where THINGS is a
     list of file-like objects denoting directories.  For example:

          (directory-union "guile+emacs" (list guile emacs))

     yields a directory that is the union of the ‘guile’ and ‘emacs’
     packages.

 -- Procedure: file-append obj suffix ...
     Return a file-like object that expands to the concatenation of OBJ
     and SUFFIX, where OBJ is a lowerable object and each SUFFIX is a
     string.

     As an example, consider this gexp:

          (gexp->script "run-uname"
                        #~(system* #$(file-append coreutils
                                                  "/bin/uname")))

     The same effect could be achieved with:

          (gexp->script "run-uname"
                        #~(system* (string-append #$coreutils
                                                  "/bin/uname")))

     There is one difference though: in the ‘file-append’ case, the
     resulting script contains the absolute file name as a string,
     whereas in the second case, the resulting script contains a
     ‘(string-append ...)’ expression to construct the file name _at run
     time_.

 -- Macro: let-system system body...
 -- Macro: let-system (system target) body...
     Bind SYSTEM to the currently targeted system—e.g.,
     ‘"x86_64-linux"’—within BODY.

     In the second case, additionally bind TARGET to the current
     cross-compilation target—a GNU triplet such as
     ‘"arm-linux-gnueabihf"’—or ‘#f’ if we are not cross-compiling.

     ‘let-system’ is useful in the occasional case where the object
     spliced into the gexp depends on the target system, as in this
     example:

          #~(system*
             #+(let-system system
                 (cond ((string-prefix? "armhf-" system)
                        (file-append qemu "/bin/qemu-system-arm"))
                       ((string-prefix? "x86_64-" system)
                        (file-append qemu "/bin/qemu-system-x86_64"))
                       (else
                        (error "dunno!"))))
             "-net" "user" #$image)

 -- Macro: with-parameters ((parameter value) ...) exp
     This macro is similar to the ‘parameterize’ form for
     dynamically-bound “parameters” (*note (guile)Parameters::).  The
     key difference is that it takes effect when the file-like object
     returned by EXP is lowered to a derivation or store item.

     A typical use of ‘with-parameters’ is to force the system in effect
     for a given object:

          (with-parameters ((%current-system "i686-linux"))
            coreutils)

     The example above returns an object that corresponds to the i686
     build of Coreutils, regardless of the current value of
     ‘%current-system’.

 -- Procedure: gexp-input OBJ [OUTPUT] [#:native? #f]
     Return a “gexp input” record for the given OUTPUT of file-like
     object OBJ, with ‘#:native?’ determining whether this is a native
     reference (as with ‘ungexp-native’) or not.

     This procedure is helpful when you want to pass a reference to a
     specific output of an object to some procedure that may not know
     about that output.  For example, assume you have this procedure,
     which takes one file-like object:

          (define (make-symlink target)
            (computed-file "the-symlink"
                           #~(symlink #$target #$output)))

     Here ‘make-symlink’ can only ever refer to the default output of
     TARGET—the ‘"out"’ output (*note Packages with Multiple Outputs::).
     To have it refer to, say, the ‘"lib"’ output of the ‘hwloc’
     package, you can call it like so:

          (make-symlink (gexp-input hwloc "lib"))

     You can also compose it like any other file-like object:

          (make-symlink
            (file-append (gexp-input hwloc "lib") "/lib/libhwloc.so"))

   Of course, in addition to gexps embedded in “host” code, there are
also modules containing build tools.  To make it clear that they are
meant to be used in the build stratum, these modules are kept in the
‘(guix build ...)’ name space.

   Internally, high-level objects are “lowered”, using their compiler,
to either derivations or store items.  For instance, lowering a package
yields a derivation, and lowering a ‘plain-file’ yields a store item.
This is achieved using the ‘lower-object’ monadic procedure.

 -- Monadic Procedure: lower-object OBJ [SYSTEM] [#:target #f]
     Return as a value in ‘%store-monad’ the derivation or store item
     corresponding to OBJ for SYSTEM, cross-compiling for TARGET if
     TARGET is true.  OBJ must be an object that has an associated gexp
     compiler, such as a ‘<package>’.

 -- Procedure: gexp->approximate-sexp gexp
     Sometimes, it may be useful to convert a G-exp into a S-exp.  For
     example, some linters (*note Invoking guix lint::) peek into the
     build phases of a package to detect potential problems.  This
     conversion can be achieved with this procedure.  However, some
     information can be lost in the process.  More specifically,
     lowerable objects will be silently replaced with some arbitrary
     object – currently the list ‘(*approximate*)’, but this may change.

   ---------- Footnotes ----------

   (1) The term “stratum” in this context was coined by Manuel Serrano
et al. in the context of their work on Hop.  Oleg Kiselyov, who has
written insightful essays and code on this topic
(http://okmij.org/ftp/meta-programming/#meta-scheme), refers to this
kind of code generation as “staging”.


File: guix.info,  Node: Invoking guix repl,  Next: Using Guix Interactively,  Prev: G-Expressions,  Up: Programming Interface

8.13 Invoking ‘guix repl’
=========================

The ‘guix repl’ command makes it easier to program Guix in Guile by
launching a Guile “read-eval-print loop” (REPL) for interactive
programming (*note (guile)Using Guile Interactively::), or by running
Guile scripts (*note (guile)Running Guile Scripts::).  Compared to just
launching the ‘guile’ command, ‘guix repl’ guarantees that all the Guix
modules and all its dependencies are available in the search path.

   The general syntax is:

     guix repl OPTIONS [FILE ARGS]

   When a FILE argument is provided, FILE is executed as a Guile script:

     guix repl my-script.scm

   To pass arguments to the script, use ‘--’ to prevent them from being
interpreted as arguments to ‘guix repl’ itself:

     guix repl -- my-script.scm --input=foo.txt

   To make a script executable directly from the shell, using the guix
executable that is on the user’s search path, add the following two
lines at the top of the script:

     #!/usr/bin/env -S guix repl --
     !#

   To make a script that launches an interactive REPL directly from the
shell, use the ‘--interactive’ flag:

     #!/usr/bin/env -S guix repl --interactive
     !#

   Without a file name argument, a Guile REPL is started, allowing for
interactive use (*note Using Guix Interactively::):

     $ guix repl
     scheme@(guile-user)> ,use (gnu packages base)
     scheme@(guile-user)> coreutils
     $1 = #<package coreutils@8.29 gnu/packages/base.scm:327 3e28300>

   In addition, ‘guix repl’ implements a simple machine-readable REPL
protocol for use by ‘(guix inferior)’, a facility to interact with
“inferiors”, separate processes running a potentially different revision
of Guix.

   The available options are as follows:

‘--list-types’
     Display the TYPE options for ‘guix repl --type=TYPE’ and exit.

‘--type=TYPE’
‘-t TYPE’
     Start a REPL of the given TYPE, which can be one of the following:

     ‘guile’
          This is default, and it spawns a standard full-featured Guile
          REPL.
     ‘machine’
          Spawn a REPL that uses the machine-readable protocol.  This is
          the protocol that the ‘(guix inferior)’ module speaks.

‘--listen=ENDPOINT’
     By default, ‘guix repl’ reads from standard input and writes to
     standard output.  When this option is passed, it will instead
     listen for connections on ENDPOINT.  Here are examples of valid
     options:

     ‘--listen=tcp:37146’
          Accept connections on localhost on port 37146.

     ‘--listen=unix:/tmp/socket’
          Accept connections on the Unix-domain socket ‘/tmp/socket’.

‘--interactive’
‘-i’
     Launch the interactive REPL after FILE is executed.

‘--load-path=DIRECTORY’
‘-L DIRECTORY’
     Add DIRECTORY to the front of the package module search path (*note
     Package Modules::).

     This allows users to define their own packages and make them
     visible to the script or REPL.

‘-q’
     Inhibit loading of the ‘~/.guile’ file.  By default, that
     configuration file is loaded when spawning a ‘guile’ REPL.


File: guix.info,  Node: Using Guix Interactively,  Prev: Invoking guix repl,  Up: Programming Interface

8.14 Using Guix Interactively
=============================

The ‘guix repl’ command gives you access to a warm and friendly
“read-eval-print loop” (REPL) (*note Invoking 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
(*note The Perfect Setup::), 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 (*note
(guile)Using Guile Modules::), but the REPL provides the ‘use’ “command”
as a shorthand notation (*note (guile)REPL Commands::):

     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” (*note ‘computed-file’:
G-Expressions.), 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 (*note Defining Package
Variants::) 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 (*note Derivations::) 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: build-options OPTIONS
     Set build options for rest of the REPL commands to OPTIONS.  Must
     be a list of keywords with values accepted by procedure ‘(@ (guix
     store) set-build-options)’.  An example would be:

          ,build-options '(#:offload? #f)

 -- REPL command: graft? GRAFT?
     Set whether grafts should be performed as part of the build.
     Equivalent to ‘--no-grafts’ argument to ‘guix build’.

 -- 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 (*note
     Common Build Options::): 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 (*note package Reference::): the first
     one show the staged code associated with ‘#:phases’ (*note Build
     Phases::), 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.  *Note The
     Store Monad::, for more information.

 -- REPL command: enter-store-monad
     Enter a new REPL to evaluate monadic expressions (*note The Store
     Monad::).  You can quit this “inner” REPL by typing ‘,q’.


File: guix.info,  Node: Utilities,  Next: Foreign Architectures,  Prev: Programming Interface,  Up: Top

9 Utilities
***********

This section describes Guix command-line utilities.  Some of them are
primarily targeted at developers and users who write new package
definitions, while others are more generally useful.  They complement
the Scheme programming interface of Guix in a convenient way.

* Menu:

* Invoking guix build::         Building packages from the command line.
* Invoking guix edit::          Editing package definitions.
* Invoking guix download::      Downloading a file and printing its hash.
* Invoking guix hash::          Computing the cryptographic hash of a file.
* Invoking guix import::        Importing package definitions.
* Invoking guix refresh::       Updating package definitions.
* Invoking guix style::         Styling package definitions.
* Invoking guix lint::          Finding errors in package definitions.
* Invoking guix size::          Profiling disk usage.
* Invoking guix graph::         Visualizing the graph of packages.
* Invoking guix publish::       Sharing substitutes.
* Invoking guix challenge::     Challenging substitute servers.
* Invoking guix copy::          Copying to and from a remote store.
* Invoking guix container::     Process isolation.
* Invoking guix weather::       Assessing substitute availability.
* Invoking guix processes::     Listing client processes.


File: guix.info,  Node: Invoking guix build,  Next: Invoking guix edit,  Up: Utilities

9.1 Invoking ‘guix build’
=========================

The ‘guix build’ command builds packages or derivations and their
dependencies, and prints the resulting store paths.  Note that it does
not modify the user’s profile—this is the job of the ‘guix package’
command (*note Invoking guix package::).  Thus, it is mainly useful for
distribution developers.

   The general syntax is:

     guix build OPTIONS PACKAGE-OR-DERIVATION...

   As an example, the following command builds the latest versions of
Emacs and of Guile, displays their build logs, and finally displays the
resulting directories:

     guix build emacs guile

   Similarly, the following command builds all the available packages:

     guix build --quiet --keep-going \
       $(guix package -A | awk '{ print $1 "@" $2 }')

   PACKAGE-OR-DERIVATION may be either the name of a package found in
the software distribution such as ‘coreutils’ or ‘coreutils@8.20’, or a
derivation such as ‘/gnu/store/...-coreutils-8.19.drv’.  In the former
case, a package with the corresponding name (and optionally version) is
searched for among the GNU distribution modules (*note Package
Modules::).

   Alternatively, the ‘--expression’ option may be used to specify a
Scheme expression that evaluates to a package; this is useful when
disambiguating among several same-named packages or package variants is
needed.

   There may be zero or more OPTIONS.  The available options are
described in the subsections below.

* Menu:

* Common Build Options::        Build options for most commands.
* Package Transformation Options::  Creating variants of packages.
* Additional Build Options::    Options specific to ’guix build’.
* Debugging Build Failures::    Real life packaging experience.


File: guix.info,  Node: Common Build Options,  Next: Package Transformation Options,  Up: Invoking guix build

9.1.1 Common Build Options
--------------------------

A number of options that control the build process are common to ‘guix
build’ and other commands that can spawn builds, such as ‘guix package’
or ‘guix archive’.  These are the following:

‘--load-path=DIRECTORY’
‘-L DIRECTORY’
     Add DIRECTORY to the front of the package module search path (*note
     Package Modules::).

     This allows users to define their own packages and make them
     visible to the command-line tools.

‘--keep-failed’
‘-K’
     Keep the build tree of failed builds.  Thus, if a build fails, its
     build tree is kept under ‘/tmp’, in a directory whose name is shown
     at the end of the build log.  This is useful when debugging build
     issues.  *Note Debugging Build Failures::, for tips and tricks on
     how to debug build issues.

     This option implies ‘--no-offload’, and it has no effect when
     connecting to a remote daemon with a ‘guix://’ URI (*note the
     ‘GUIX_DAEMON_SOCKET’ variable: The Store.).

‘--keep-going’
‘-k’
     Keep going when some of the derivations fail to build; return only
     once all the builds have either completed or failed.

     The default behavior is to stop as soon as one of the specified
     derivations has failed.

‘--dry-run’
‘-n’
     Do not build the derivations.

‘--fallback’
     When substituting a pre-built binary fails, fall back to building
     packages locally (*note Substitution Failure::).

‘--substitute-urls=URLS’
     Consider URLS the whitespace-separated list of substitute source
     URLs, overriding the default list of URLs of ‘guix-daemon’ (*note
     ‘guix-daemon’ URLs: daemon-substitute-urls.).

     This means that substitutes may be downloaded from URLS, provided
     they are signed by a key authorized by the system administrator
     (*note Substitutes::).

     When URLS is the empty string, substitutes are effectively
     disabled.

‘--no-substitutes’
     Do not use substitutes for build products.  That is, always build
     things locally instead of allowing downloads of pre-built binaries
     (*note Substitutes::).

‘--no-grafts’
     Do not “graft” packages.  In practice, this means that package
     updates available as grafts are not applied.  *Note Security
     Updates::, for more information on grafts.

‘--rounds=N’
     Build each derivation N times in a row, and raise an error if
     consecutive build results are not bit-for-bit identical.

     This is a useful way to detect non-deterministic builds processes.
     Non-deterministic build processes are a problem because they make
     it practically impossible for users to _verify_ whether third-party
     binaries are genuine.  *Note Invoking guix challenge::, for more.

     When used in conjunction with ‘--keep-failed’, the differing output
     is kept in the store, under ‘/gnu/store/...-check’.  This makes it
     easy to look for differences between the two results.

‘--no-offload’
     Do not use offload builds to other machines (*note Daemon Offload
     Setup::).  That is, always build things locally instead of
     offloading builds to remote machines.

‘--max-silent-time=SECONDS’
     When the build or substitution process remains silent for more than
     SECONDS, terminate it and report a build failure.

     By default, the daemon’s setting is honored (*note
     ‘--max-silent-time’: Invoking guix-daemon.).

‘--timeout=SECONDS’
     Likewise, when the build or substitution process lasts for more
     than SECONDS, terminate it and report a build failure.

     By default, the daemon’s setting is honored (*note ‘--timeout’:
     Invoking guix-daemon.).

‘-v LEVEL’
‘--verbosity=LEVEL’
     Use the given verbosity LEVEL, an integer.  Choosing 0 means that
     no output is produced, 1 is for quiet output; 2 is similar to 1 but
     it additionally displays download URLs; 3 shows all the build log
     output on standard error.

‘--cores=N’
‘-c N’
     Allow the use of up to N CPU cores for the build.  The special
     value ‘0’ means to use as many CPU cores as available.

‘--max-jobs=N’
‘-M N’
     Allow at most N build jobs in parallel.  *Note ‘--max-jobs’:
     Invoking guix-daemon, for details about this option and the
     equivalent ‘guix-daemon’ option.

‘--debug=LEVEL’
     Produce debugging output coming from the build daemon.  LEVEL must
     be an integer between 0 and 5; higher means more verbose output.
     Setting a level of 4 or more may be helpful when debugging setup
     issues with the build daemon.

   Behind the scenes, ‘guix build’ is essentially an interface to the
‘package-derivation’ procedure of the ‘(guix packages)’ module, and to
the ‘build-derivations’ procedure of the ‘(guix derivations)’ module.

   In addition to options explicitly passed on the command line, ‘guix
build’ and other ‘guix’ commands that support building honor the
‘GUIX_BUILD_OPTIONS’ environment variable.

 -- Environment Variable: GUIX_BUILD_OPTIONS
     Users can define this variable to a list of command line options
     that will automatically be used by ‘guix build’ and other ‘guix’
     commands that can perform builds, as in the example below:

          $ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"

     These options are parsed independently, and the result is appended
     to the parsed command-line options.


File: guix.info,  Node: Package Transformation Options,  Next: Additional Build Options,  Prev: Common Build Options,  Up: Invoking guix build

9.1.2 Package Transformation Options
------------------------------------

Another set of command-line options supported by ‘guix build’ and also
‘guix package’ are “package transformation options”.  These are options
that make it possible to define “package variants”—for instance,
packages built from different source code.  This is a convenient way to
create customized packages on the fly without having to type in the
definitions of package variants (*note Defining Packages::).

   Package transformation options are preserved across upgrades: ‘guix
upgrade’ attempts to apply transformation options initially used when
creating the profile to the upgraded packages.

   The available options are listed below.  Most commands support them
and also support a ‘--help-transform’ option that lists all the
available options and a synopsis (these options are not shown in the
‘--help’ output for brevity).

‘--tune[=CPU]’
     Use versions of the packages marked as “tunable” optimized for CPU.
     When CPU is ‘native’, or when it is omitted, tune for the CPU on
     which the ‘guix’ command is running.

     Valid CPU names are those recognized by the underlying compiler, by
     default the GNU Compiler Collection.  On x86_64 processors, this
     includes CPU names such as ‘nehalem’, ‘haswell’, and ‘skylake’
     (*note ‘-march’: (gcc)x86 Options.).

     As new generations of CPUs come out, they augment the standard
     instruction set architecture (ISA) with additional instructions, in
     particular instructions for single-instruction/multiple-data (SIMD)
     parallel processing.  For example, while Core2 and Skylake CPUs
     both implement the x86_64 ISA, only the latter supports AVX2 SIMD
     instructions.

     The primary gain one can expect from ‘--tune’ is for programs that
     can make use of those SIMD capabilities _and_ that do not already
     have a mechanism to select the right optimized code at run time.
     Packages that have the ‘tunable?’ property set are considered
     “tunable packages” by the ‘--tune’ option; a package definition
     with the property set looks like this:

          (package
            (name "hello-simd")
            ;; ...

            ;; This package may benefit from SIMD extensions so
            ;; mark it as "tunable".
            (properties '((tunable? . #t))))

     Other packages are not considered tunable.  This allows Guix to use
     generic binaries in the cases where tuning for a specific CPU is
     unlikely to provide any gain.

     Tuned packages are built with ‘-march=CPU’; under the hood, the
     ‘-march’ option is passed to the actual wrapper by a compiler
     wrapper.  Since the build machine may not be able to run code for
     the target CPU micro-architecture, the test suite is not run when
     building a tuned package.

     To reduce rebuilds to the minimum, tuned packages are _grafted_
     onto packages that depend on them (*note grafts: Security
     Updates.).  Thus, using ‘--no-grafts’ cancels the effect of
     ‘--tune’.

     We call this technique “package multi-versioning”: several variants
     of tunable packages may be built, one for each CPU variant.  It is
     the coarse-grain counterpart of “function multi-versioning” as
     implemented by the GNU tool chain (*note (gcc)Function
     Multiversioning::).

‘--with-source=SOURCE’
‘--with-source=PACKAGE=SOURCE’
‘--with-source=PACKAGE@VERSION=SOURCE’
     Use SOURCE as the source of PACKAGE, and VERSION as its version
     number.  SOURCE must be a file name or a URL, as for ‘guix
     download’ (*note Invoking guix download::).

     When PACKAGE is omitted, it is taken to be the package name
     specified on the command line that matches the base of SOURCE—e.g.,
     if SOURCE is ‘/src/guile-2.0.10.tar.gz’, the corresponding package
     is ‘guile’.

     Likewise, when VERSION is omitted, the version string is inferred
     from SOURCE; in the previous example, it is ‘2.0.10’.

     This option allows users to try out versions of packages other than
     the one provided by the distribution.  The example below downloads
     ‘ed-1.7.tar.gz’ from a GNU mirror and uses that as the source for
     the ‘ed’ package:

          guix build ed --with-source=mirror://gnu/ed/ed-1.4.tar.gz

     As a developer, ‘--with-source’ makes it easy to test release
     candidates, and even to test their impact on packages that depend
     on them:

          guix build elogind --with-source=.../shepherd-0.9.0rc1.tar.gz

     ... or to build from a checkout in a pristine environment:

          $ git clone git://git.sv.gnu.org/guix.git
          $ guix build guix --with-source=guix@1.0=./guix

‘--with-input=PACKAGE=REPLACEMENT’
     Replace dependency on PACKAGE by a dependency on REPLACEMENT.
     PACKAGE must be a package name, and REPLACEMENT must be a package
     specification such as ‘guile’ or ‘guile@1.8’.

     For instance, the following command builds Guix, but replaces its
     dependency on the current stable version of Guile with a dependency
     on the legacy version of Guile, ‘guile@2.2’:

          guix build --with-input=guile=guile@2.2 guix

     This is a recursive, deep replacement.  So in this example, both
     ‘guix’ and its dependency ‘guile-json’ (which also depends on
     ‘guile’) get rebuilt against ‘guile@2.2’.

     This is implemented using the ‘package-input-rewriting/spec’ Scheme
     procedure (*note ‘package-input-rewriting/spec’: Defining
     Packages.).

‘--with-graft=PACKAGE=REPLACEMENT’
     This is similar to ‘--with-input’ but with an important difference:
     instead of rebuilding the whole dependency chain, REPLACEMENT is
     built and then “grafted” onto the binaries that were initially
     referring to PACKAGE.  *Note Security Updates::, for more
     information on grafts.

     For example, the command below grafts version 3.5.4 of GnuTLS onto
     Wget and all its dependencies, replacing references to the version
     of GnuTLS they currently refer to:

          guix build --with-graft=gnutls=gnutls@3.5.4 wget

     This has the advantage of being much faster than rebuilding
     everything.  But there is a caveat: it works if and only if PACKAGE
     and REPLACEMENT are strictly compatible—for example, if they
     provide a library, the application binary interface (ABI) of those
     libraries must be compatible.  If REPLACEMENT is somehow
     incompatible with PACKAGE, then the resulting package may be
     unusable.  Use with care!

‘--with-debug-info=PACKAGE’
     Build PACKAGE in a way that preserves its debugging info and graft
     it onto packages that depend on it.  This is useful if PACKAGE does
     not already provide debugging info as a ‘debug’ output (*note
     Installing Debugging Files::).

     For example, suppose you’re experiencing a crash in Inkscape and
     would like to see what’s up in GLib, a library deep down in
     Inkscape’s dependency graph.  GLib lacks a ‘debug’ output, so
     debugging is tough.  Fortunately, you rebuild GLib with debugging
     info and tack it on Inkscape:

          guix install inkscape --with-debug-info=glib

     Only GLib needs to be recompiled so this takes a reasonable amount
     of time.  *Note Installing Debugging Files::, for more info.

          Note: Under the hood, this option works by passing the
          ‘#:strip-binaries? #f’ to the build system of the package of
          interest (*note Build Systems::).  Most build systems support
          that option but some do not.  In that case, an error is
          raised.

          Likewise, if a C/C++ package is built without ‘-g’ (which is
          rarely the case), debugging info will remain unavailable even
          when ‘#:strip-binaries?’ is false.

‘--with-c-toolchain=PACKAGE=TOOLCHAIN’
     This option changes the compilation of PACKAGE and everything that
     depends on it so that they get built with TOOLCHAIN instead of the
     default GNU tool chain for C/C++.

     Consider this example:

          guix build octave-cli \
            --with-c-toolchain=fftw=gcc-toolchain@10 \
            --with-c-toolchain=fftwf=gcc-toolchain@10

     The command above builds a variant of the ‘fftw’ and ‘fftwf’
     packages using version 10 of ‘gcc-toolchain’ instead of the default
     tool chain, and then builds a variant of the GNU Octave
     command-line interface using them.  GNU Octave itself is also built
     with ‘gcc-toolchain@10’.

     This other example builds the Hardware Locality (‘hwloc’) library
     and its dependents up to ‘intel-mpi-benchmarks’ with the Clang C
     compiler:

          guix build --with-c-toolchain=hwloc=clang-toolchain \
                     intel-mpi-benchmarks

          Note: There can be application binary interface (ABI)
          incompatibilities among tool chains.  This is particularly
          true of the C++ standard library and run-time support
          libraries such as that of OpenMP.  By rebuilding all
          dependents with the same tool chain, ‘--with-c-toolchain’
          minimizes the risks of incompatibility but cannot entirely
          eliminate them.  Choose PACKAGE wisely.

‘--with-git-url=PACKAGE=URL’
     Build PACKAGE from the latest commit of the ‘master’ branch of the
     Git repository at URL.  Git sub-modules of the repository are
     fetched, recursively, if PACKAGE ‘source’ is not a Git repository,
     otherwise it depends on the inherited value of ‘recursive?’.

     For example, the following command builds the NumPy Python library
     against the latest commit of the master branch of Python itself:

          guix build python-numpy \
            --with-git-url=python=https://github.com/python/cpython

     This option can also be combined with ‘--with-branch’ or
     ‘--with-commit’ (see below).

     Obviously, since it uses the latest commit of the given branch, the
     result of such a command varies over time.  Nevertheless it is a
     convenient way to rebuild entire software stacks against the latest
     commit of one or more packages.  This is particularly useful in the
     context of continuous integration (CI).

     Checkouts are kept in a cache under ‘~/.cache/guix/checkouts’ to
     speed up consecutive accesses to the same repository.  You may want
     to clean it up once in a while to save disk space.

‘--with-branch=PACKAGE=BRANCH’
     Build PACKAGE from the latest commit of BRANCH.  If the ‘source’
     field of PACKAGE is an origin with the ‘git-fetch’ method (*note
     origin Reference::) or a ‘git-checkout’ object, the repository URL
     is taken from that ‘source’.  Otherwise you have to use
     ‘--with-git-url’ to specify the URL of the Git repository.

     For instance, the following command builds ‘guile-sqlite3’ from the
     latest commit of its ‘master’ branch, and then builds ‘guix’ (which
     depends on it) and ‘cuirass’ (which depends on ‘guix’) against this
     specific ‘guile-sqlite3’ build:

          guix build --with-branch=guile-sqlite3=master cuirass

‘--with-commit=PACKAGE=COMMIT’
     This is similar to ‘--with-branch’, except that it builds from
     COMMIT rather than the tip of a branch.  COMMIT must be a valid Git
     commit SHA1 identifier, a tag, or a ‘git describe’ style identifier
     such as ‘1.0-3-gabc123’.

‘--with-patch=PACKAGE=FILE’
     Add FILE to the list of patches applied to PACKAGE, where PACKAGE
     is a spec such as ‘python@3.8’ or ‘glibc’.  FILE must contain a
     patch; it is applied with the flags specified in the ‘origin’ of
     PACKAGE (*note origin Reference::), which by default includes ‘-p1’
     (*note (diffutils)patch Directories::).

     As an example, the command below rebuilds Coreutils with the GNU C
     Library (glibc) patched with the given patch:

          guix build coreutils --with-patch=glibc=./glibc-frob.patch

     In this example, glibc itself as well as everything that leads to
     Coreutils in the dependency graph is rebuilt.

‘--with-configure-flag=PACKAGE=FLAG’
     Append FLAG to the configure flags of PACKAGE, where PACKAGE is a
     spec such as ‘guile@3.0’ or ‘glibc’.  The build system of PACKAGE
     must support the ‘#:configure-flags’ argument.

     For example, the command below builds GNU Hello with the configure
     flag ‘--disable-nls’:

          guix build hello --with-configure-flag=hello=--disable-nls

     The following command passes an extra flag to ‘cmake’ as it builds
     ‘lapack’:

          guix build lapack \
            --with-configure-flag=lapack=-DBUILD_SHARED_LIBS=OFF

          Note: Under the hood, this option works by passing the
          ‘#:configure-flags’ argument to the build system of the
          package of interest (*note Build Systems::).  Most build
          systems support that option but some do not.  In that case, an
          error is raised.

‘--with-latest=PACKAGE’
‘--with-version=PACKAGE=VERSION’
     So you like living on the bleeding edge?  The ‘--with-latest’
     option is for you!  It replaces occurrences of PACKAGE in the
     dependency graph with its latest upstream version, as reported by
     ‘guix refresh’ (*note Invoking guix refresh::).

     It does so by determining the latest upstream release of PACKAGE
     (if possible), downloading it, and authenticating it _if_ it comes
     with an OpenPGP signature.

     As an example, the command below builds Guix against the latest
     version of Guile-JSON:

          guix build guix --with-latest=guile-json

     The ‘--with-version’ works similarly except that it lets you
     specify that you want precisely VERSION, assuming that version
     exists upstream.  For example, to spawn a development environment
     with SciPy built against version 1.22.4 of NumPy (skipping its test
     suite because hey, we’re not gonna wait this long), you would run:

          guix shell python python-scipy --with-version=python-numpy=1.22.4

          Warning: Because they depend on source code published at a
          given point in time on upstream servers, deployments made with
          ‘--with-latest’ and ‘--with-version’ may be non-reproducible:
          source might disappear or be modified in place on the servers.

          To deploy old software versions without compromising on
          reproducibility, *note ‘guix time-machine’: Invoking guix
          time-machine.

     There are limitations.  First, in cases where the tool cannot or
     does not know how to authenticate source code, you are at risk of
     running malicious code; a warning is emitted in this case.  Second,
     this option simply changes the source used in the existing package
     definitions, which is not always sufficient: there might be
     additional dependencies that need to be added, patches to apply,
     and more generally the quality assurance work that Guix developers
     normally do will be missing.

     You’ve been warned!  When those limitations are acceptable, it’s a
     snappy way to stay on top.  We encourage you to submit patches
     updating the actual package definitions once you have successfully
     tested an upgrade with ‘--with-latest’ (*note Contributing::).

‘--without-tests=PACKAGE’
     Build PACKAGE without running its tests.  This can be useful in
     situations where you want to skip the lengthy test suite of a
     intermediate package, or if a package’s test suite fails in a
     non-deterministic fashion.  It should be used with care because
     running the test suite is a good way to ensure a package is working
     as intended.

     Turning off tests leads to a different store item.  Consequently,
     when using this option, anything that depends on PACKAGE must be
     rebuilt, as in this example:

          guix install --without-tests=python python-notebook

     The command above installs ‘python-notebook’ on top of ‘python’
     built without running its test suite.  To do so, it also rebuilds
     everything that depends on ‘python’, including ‘python-notebook’
     itself.

     Internally, ‘--without-tests’ relies on changing the ‘#:tests?’
     option of a package’s ‘check’ phase (*note Build Systems::).  Note
     that some packages use a customized ‘check’ phase that does not
     respect a ‘#:tests? #f’ setting.  Therefore, ‘--without-tests’ has
     no effect on these packages.

   Wondering how to achieve the same effect using Scheme code, for
example in your manifest, or how to write your own package
transformation?  *Note Defining Package Variants::, for an overview of
the programming interfaces available.


File: guix.info,  Node: Additional Build Options,  Next: Debugging Build Failures,  Prev: Package Transformation Options,  Up: Invoking guix build

9.1.3 Additional Build Options
------------------------------

The command-line options presented below are specific to ‘guix build’.

‘--quiet’
‘-q’
     Build quietly, without displaying the build log; this is equivalent
     to ‘--verbosity=0’.  Upon completion, the build log is kept in
     ‘/var’ (or similar) and can always be retrieved using the
     ‘--log-file’ option.

‘--file=FILE’
‘-f FILE’
     Build the package, derivation, or other file-like object that the
     code within FILE evaluates to (*note file-like objects:
     G-Expressions.).

     As an example, FILE might contain a package definition like this
     (*note Defining Packages::):

          (use-modules (guix)
                       (guix build-system gnu)
                       (guix licenses))

          (package
            (name "hello")
            (version "2.10")
            (source (origin
                      (method url-fetch)
                      (uri (string-append "mirror://gnu/hello/hello-" version
                                          ".tar.gz"))
                      (sha256
                       (base32
                        "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
            (build-system gnu-build-system)
            (synopsis "Hello, GNU world: An example GNU package")
            (description "Guess what GNU Hello prints!")
            (home-page "http://www.gnu.org/software/hello/")
            (license gpl3+))

     The FILE may also contain a JSON representation of one or more
     package definitions.  Running ‘guix build -f’ on ‘hello.json’ with
     the following contents would result in building the packages
     ‘myhello’ and ‘greeter’:

          [
            {
              "name": "myhello",
              "version": "2.10",
              "source": "mirror://gnu/hello/hello-2.10.tar.gz",
              "build-system": "gnu",
              "arguments": {
                "tests?": false
              },
              "home-page": "https://www.gnu.org/software/hello/",
              "synopsis": "Hello, GNU world: An example GNU package",
              "description": "GNU Hello prints a greeting.",
              "license": "GPL-3.0+",
              "native-inputs": ["gettext"]
            },
            {
              "name": "greeter",
              "version": "1.0",
              "source": "mirror://gnu/hello/hello-2.10.tar.gz",
              "build-system": "gnu",
              "arguments": {
                "test-target": "foo",
                "parallel-build?": false
              },
              "home-page": "https://example.com/",
              "synopsis": "Greeter using GNU Hello",
              "description": "This is a wrapper around GNU Hello.",
              "license": "GPL-3.0+",
              "inputs": ["myhello", "hello"]
            }
          ]

‘--manifest=MANIFEST’
‘-m MANIFEST’
     Build all packages listed in the given MANIFEST (*note
     ‘--manifest’: profile-manifest.).

‘--expression=EXPR’
‘-e EXPR’
     Build the package or derivation EXPR evaluates to.

     For example, EXPR may be ‘(@ (gnu packages guile) guile-1.8)’,
     which unambiguously designates this specific variant of version 1.8
     of Guile.

     Alternatively, EXPR may be a G-expression, in which case it is used
     as a build program passed to ‘gexp->derivation’ (*note
     G-Expressions::).

     Lastly, EXPR may refer to a zero-argument monadic procedure (*note
     The Store Monad::).  The procedure must return a derivation as a
     monadic value, which is then passed through ‘run-with-store’.

‘--development’
‘-D’
     Build the “development environment” (build dependencies) of the
     following package.

     For example, the following command builds the inputs of ‘hello’,
     but _not_ ‘hello’ itself, and also builds ‘guile’:

          guix build -D hello guile

     Notice that ‘-D’ (or ‘--development’) only applies to the
     immediately following package on the command line.  Under the hood,
     it uses ‘package->development-manifest’ (*note
     ‘package->development-manifest’: package-development-manifest.).

          Note: The effect of combining ‘--development’ with ‘--target’
          (for cross-compilation) may not be what you expect: it will
          cross-compile all the dependencies of the given package when
          it is built natively.

‘--dependents[=DEPTH]’
‘-P DEPTH’
     Build the dependents of the following package.  By default, build
     all the direct and indirect dependents; when DEPTH is provided,
     limit to dependents at that distance: 1 for direct dependents, 2
     for dependents of dependents, and so on.

     For example, the command below builds _all_ the dependents of
     libgit2:

          guix build --dependents libgit2

     To build all the packages that directly depend on NumPy, run:

          guix build -P1 python-numpy

     The list of dependents is computed in the same way as with ‘guix
     refresh --list-dependent’ (*note Invoking guix refresh::).

‘--source’
‘-S’
     Build the source derivations of the packages, rather than the
     packages themselves.

     For instance, ‘guix build -S gcc’ returns something like
     ‘/gnu/store/...-gcc-4.7.2.tar.bz2’, which is the GCC source
     tarball.

     The returned source tarball is the result of applying any patches
     and code snippets specified in the package ‘origin’ (*note Defining
     Packages::).

     As with other derivations, the result of building a source
     derivation can be verified using the ‘--check’ option (*note
     build-check::).  This is useful to validate that a (potentially
     already built or substituted, thus cached) package source matches
     against its declared hash.

     Note that ‘guix build -S’ compiles the sources only of the
     specified packages.  They do not include the sources of statically
     linked dependencies and by themselves are insufficient for
     reproducing the packages.

‘--sources’
     Fetch and return the source of PACKAGE-OR-DERIVATION and all their
     dependencies, recursively.  This is a handy way to obtain a local
     copy of all the source code needed to build PACKAGES, allowing you
     to eventually build them even without network access.  It is an
     extension of the ‘--source’ option and can accept one of the
     following optional argument values:

     ‘package’
          This value causes the ‘--sources’ option to behave in the same
          way as the ‘--source’ option.

     ‘all’
          Build the source derivations of all packages, including any
          source that might be listed as ‘inputs’.  This is the default
          value.

               $ guix build --sources tzdata
               The following derivations will be built:
                  /gnu/store/...-tzdata2015b.tar.gz.drv
                  /gnu/store/...-tzcode2015b.tar.gz.drv

     ‘transitive’
          Build the source derivations of all packages, as well of all
          transitive inputs to the packages.  This can be used e.g. to
          prefetch package source for later offline building.

               $ guix build --sources=transitive tzdata
               The following derivations will be built:
                  /gnu/store/...-tzcode2015b.tar.gz.drv
                  /gnu/store/...-findutils-4.4.2.tar.xz.drv
                  /gnu/store/...-grep-2.21.tar.xz.drv
                  /gnu/store/...-coreutils-8.23.tar.xz.drv
                  /gnu/store/...-make-4.1.tar.xz.drv
                  /gnu/store/...-bash-4.3.tar.xz.drv
               ...

‘--system=SYSTEM’
‘-s SYSTEM’
     Attempt to build for SYSTEM—e.g., ‘i686-linux’—instead of the
     system type of the build host.  The ‘guix build’ command allows you
     to repeat this option several times, in which case it builds for
     all the specified systems; other commands ignore extraneous ‘-s’
     options.

          Note: The ‘--system’ flag is for _native_ compilation and must
          not be confused with cross-compilation.  See ‘--target’ below
          for information on cross-compilation.

     An example use of this is on Linux-based systems, which can emulate
     different personalities.  For instance, passing
     ‘--system=i686-linux’ on an ‘x86_64-linux’ system or
     ‘--system=armhf-linux’ on an ‘aarch64-linux’ system allows you to
     build packages in a complete 32-bit environment.

          Note: Building for an ‘armhf-linux’ system is unconditionally
          enabled on ‘aarch64-linux’ machines, although certain aarch64
          chipsets do not allow for this functionality, notably the
          ThunderX.

     Similarly, when transparent emulation with QEMU and ‘binfmt_misc’
     is enabled (*note ‘qemu-binfmt-service-type’: Virtualization
     Services.), you can build for any system for which a QEMU
     ‘binfmt_misc’ handler is installed.

     Builds for a system other than that of the machine you are using
     can also be offloaded to a remote machine of the right
     architecture.  *Note Daemon Offload Setup::, for more information
     on offloading.

‘--target=TRIPLET’
     Cross-build for TRIPLET, which must be a valid GNU triplet, such as
     ‘"aarch64-linux-gnu"’ (*note GNU configuration triplets:
     (autoconf)Specifying Target Triplets.).

‘--list-systems’
     List all the supported systems, that can be passed as an argument
     to ‘--system’.

‘--list-targets’
     List all the supported targets, that can be passed as an argument
     to ‘--target’.

‘--check’
     Rebuild PACKAGE-OR-DERIVATION, which are already available in the
     store, and raise an error if the build results are not bit-for-bit
     identical.

     This mechanism allows you to check whether previously installed
     substitutes are genuine (*note Substitutes::), or whether the build
     result of a package is deterministic.  *Note Invoking guix
     challenge::, for more background information and tools.

     When used in conjunction with ‘--keep-failed’, the differing output
     is kept in the store, under ‘/gnu/store/...-check’.  This makes it
     easy to look for differences between the two results.

‘--repair’
     Attempt to repair the specified store items, if they are corrupt,
     by re-downloading or rebuilding them.

     This operation is not atomic and thus restricted to ‘root’.

‘--derivations’
‘-d’
     Return the derivation paths, not the output paths, of the given
     packages.

‘--root=FILE’
‘-r FILE’
     Make FILE a symlink to the result, and register it as a garbage
     collector root.

     Consequently, the results of this ‘guix build’ invocation are
     protected from garbage collection until FILE is removed.  When that
     option is omitted, build results are eligible for garbage
     collection as soon as the build completes.  *Note Invoking guix
     gc::, for more on GC roots.

‘--log-file’
     Return the build log file names or URLs for the given
     PACKAGE-OR-DERIVATION, or raise an error if build logs are missing.

     This works regardless of how packages or derivations are specified.
     For instance, the following invocations are equivalent:

          guix build --log-file $(guix build -d guile)
          guix build --log-file $(guix build guile)
          guix build --log-file guile
          guix build --log-file -e '(@ (gnu packages guile) guile-2.0)'

     If a log is unavailable locally, and unless ‘--no-substitutes’ is
     passed, the command looks for a corresponding log on one of the
     substitute servers.

     So for instance, imagine you want to see the build log of GDB on
     ‘aarch64’, but you are actually on an ‘x86_64’ machine:

          $ guix build --log-file gdb -s aarch64-linux
          https://bordeaux.guix.gnu.org/log/...-gdb-7.10

     You can freely access a huge library of build logs!


File: guix.info,  Node: Debugging Build Failures,  Prev: Additional Build Options,  Up: Invoking guix build

9.1.4 Debugging Build Failures
------------------------------

When defining a new package (*note Defining Packages::), you will
probably find yourself spending some time debugging and tweaking the
build until it succeeds.  To do that, you need to operate the build
commands yourself in an environment as close as possible to the one the
build daemon uses.

   To that end, the first thing to do is to use the ‘--keep-failed’ or
‘-K’ option of ‘guix build’, which will keep the failed build tree in
‘/tmp’ or whatever directory you specified as ‘TMPDIR’ (*note
‘--keep-failed’: Common Build Options.).

   From there on, you can ‘cd’ to the failed build tree and source the
‘environment-variables’ file, which contains all the environment
variable definitions that were in place when the build failed.  So let’s
say you’re debugging a build failure in package ‘foo’; a typical session
would look like this:

     $ guix build foo -K
     ... build fails
     $ cd /tmp/guix-build-foo.drv-0
     $ source ./environment-variables
     $ cd foo-1.2

   Now, you can invoke commands as if you were the daemon (almost) and
troubleshoot your build process.

   Sometimes it happens that, for example, a package’s tests pass when
you run them manually but they fail when the daemon runs them.  This can
happen because the daemon runs builds in containers where, unlike in our
environment above, network access is missing, ‘/bin/sh’ does not exist,
etc.  (*note Build Environment Setup::).

   In such cases, you may need to inspect the build process from within
a container similar to the one the build daemon creates:

     $ guix build -K foo
     ...
     $ cd /tmp/guix-build-foo.drv-0
     $ guix shell --no-grafts -C -D foo strace gdb
     [env]# source ./environment-variables
     [env]# cd foo-1.2

   Here, ‘guix shell -C’ creates a container and spawns a new shell in
it (*note Invoking guix shell::).  The ‘strace gdb’ part adds the
‘strace’ and ‘gdb’ commands to the container, which you may find handy
while debugging.  The ‘--no-grafts’ option makes sure we get the exact
same environment, with ungrafted packages (*note Security Updates::, for
more info on grafts).

   To get closer to a container like that used by the build daemon, we
can remove ‘/bin/sh’ (you’ll first need to pass the ‘--writable-root’
option to ‘guix shell’):

     [env]# rm /bin/sh

   (Don’t worry, this is harmless: this is all happening in the
throw-away container created by ‘guix shell’.)

   The ‘strace’ command is probably not in the search path, but we can
run:

     [env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check

   In this way, not only you will have reproduced the environment
variables the daemon uses, you will also be running the build process in
a container similar to the one the daemon uses.


File: guix.info,  Node: Invoking guix edit,  Next: Invoking guix download,  Prev: Invoking guix build,  Up: Utilities

9.2 Invoking ‘guix edit’
========================

So many packages, so many source files!  The ‘guix edit’ command
facilitates the life of users and packagers by pointing their editor at
the source file containing the definition of the specified packages.
For instance:

     guix edit gcc@4.9 vim

launches the program specified in the ‘VISUAL’ or in the ‘EDITOR’
environment variable to view the recipe of GCC 4.9.3 and that of Vim.

   If you are using a Guix Git checkout (*note Building from Git::), or
have created your own packages on ‘GUIX_PACKAGE_PATH’ (*note Package
Modules::), you will be able to edit the package recipes.  In other
cases, you will be able to examine the read-only recipes for packages
currently in the store.

   Instead of ‘GUIX_PACKAGE_PATH’, the command-line option
‘--load-path=DIRECTORY’ (or in short ‘-L DIRECTORY’) allows you to add
DIRECTORY to the front of the package module search path and so make
your own packages visible.


File: guix.info,  Node: Invoking guix download,  Next: Invoking guix hash,  Prev: Invoking guix edit,  Up: Utilities

9.3 Invoking ‘guix download’
============================

When writing a package definition, developers typically need to download
a source tarball, compute its SHA256 hash, and write that hash in the
package definition (*note Defining Packages::).  The ‘guix download’
tool helps with this task: it downloads a file from the given URI, adds
it to the store, and prints both its file name in the store and its
SHA256 hash.

   The fact that the downloaded file is added to the store saves
bandwidth: when the developer eventually tries to build the newly
defined package with ‘guix build’, the source tarball will not have to
be downloaded again because it is already in the store.  It is also a
convenient way to temporarily stash files, which may be deleted
eventually (*note Invoking guix gc::).

   The ‘guix download’ command supports the same URIs as used in package
definitions.  In particular, it supports ‘mirror://’ URIs.  ‘https’ URIs
(HTTP over TLS) are supported _provided_ the Guile bindings for GnuTLS
are available in the user’s environment; when they are not available, an
error is raised.  *Note how to install the GnuTLS bindings for Guile:
(gnutls-guile)Guile Preparations, for more information.

   ‘guix download’ verifies HTTPS server certificates by loading the
certificates of X.509 authorities from the directory pointed to by the
‘SSL_CERT_DIR’ environment variable (*note X.509 Certificates::), unless
‘--no-check-certificate’ is used.

   Alternatively, ‘guix download’ can also retrieve a Git repository,
possibly a specific commit, tag, or branch.

   The following options are available:

‘--hash=ALGORITHM’
‘-H ALGORITHM’
     Compute a hash using the specified ALGORITHM.  *Note Invoking guix
     hash::, for more information.

‘--format=FMT’
‘-f FMT’
     Write the hash in the format specified by FMT.  For more
     information on the valid values for FMT, *note Invoking guix
     hash::.

‘--no-check-certificate’
     Do not validate the X.509 certificates of HTTPS servers.

     When using this option, you have _absolutely no guarantee_ that you
     are communicating with the authentic server responsible for the
     given URL, which makes you vulnerable to “man-in-the-middle”
     attacks.

‘--output=FILE’
‘-o FILE’
     Save the downloaded file to FILE instead of adding it to the store.

‘--git’
‘-g’
     Checkout the Git repository at the latest commit on the default
     branch.

‘--commit=COMMIT-OR-TAG’
     Checkout the Git repository at COMMIT-OR-TAG.

     COMMIT-OR-TAG can be either a tag or a commit defined in the Git
     repository.

‘--branch=BRANCH’
     Checkout the Git repository at BRANCH.

     The repository will be checked out at the latest commit of BRANCH,
     which must be a valid branch of the Git repository.

‘--recursive’
‘-r’
     Recursively clone the Git repository.


File: guix.info,  Node: Invoking guix hash,  Next: Invoking guix import,  Prev: Invoking guix download,  Up: Utilities

9.4 Invoking ‘guix hash’
========================

The ‘guix hash’ command computes the hash of a file.  It is primarily a
convenience tool for anyone contributing to the distribution: it
computes the cryptographic hash of one or more files, which can be used
in the definition of a package (*note Defining Packages::).

   The general syntax is:

     guix hash OPTION FILE ...

   When FILE is ‘-’ (a hyphen), ‘guix hash’ computes the hash of data
read from standard input.  ‘guix hash’ has the following options:

‘--hash=ALGORITHM’
‘-H ALGORITHM’
     Compute a hash using the specified ALGORITHM, ‘sha256’ by default.

     ALGORITHM must be the name of a cryptographic hash algorithm
     supported by Libgcrypt via Guile-Gcrypt—e.g., ‘sha512’ or
     ‘sha3-256’ (*note (guile-gcrypt)Hash Functions::).

‘--format=FMT’
‘-f FMT’
     Write the hash in the format specified by FMT.

     Supported formats: ‘base64’, ‘nix-base32’, ‘base32’, ‘base16’
     (‘hex’ and ‘hexadecimal’ can be used as well).

     If the ‘--format’ option is not specified, ‘guix hash’ will output
     the hash in ‘nix-base32’.  This representation is used in the
     definitions of packages.

‘--recursive’
‘-r’
     The ‘--recursive’ option is deprecated in favor of
     ‘--serializer=nar’ (see below); ‘-r’ remains accepted as a
     convenient shorthand.

‘--serializer=TYPE’
‘-S TYPE’
     Compute the hash on FILE using TYPE serialization.

     TYPE may be one of the following:

     ‘none’
          This is the default: it computes the hash of a file’s
          contents.

     ‘nar’
          Compute the hash of a “normalized archive” (or “nar”)
          containing FILE, including its children if it is a directory.
          Some of the metadata of FILE is part of the archive; for
          instance, when FILE is a regular file, the hash is different
          depending on whether FILE is executable or not.  Metadata such
          as time stamps have no impact on the hash (*note Invoking guix
          archive::, for more info on the nar format).

     ‘git’
          Compute the hash of the file or directory as a Git “tree”,
          following the same method as the Git version control system.

‘--exclude-vcs’
‘-x’
     When combined with ‘--recursive’, exclude version control system
     directories (‘.bzr’, ‘.git’, ‘.hg’, etc.).

     As an example, here is how you would compute the hash of a Git
     checkout, which is useful when using the ‘git-fetch’ method (*note
     origin Reference::):

          $ git clone http://example.org/foo.git
          $ cd foo
          $ guix hash -x --serializer=nar .


File: guix.info,  Node: Invoking guix import,  Next: Invoking guix refresh,  Prev: Invoking guix hash,  Up: Utilities

9.5 Invoking ‘guix import’
==========================

The ‘guix import’ command is useful for people who would like to add a
package to the distribution with as little work as possible—a legitimate
demand.  The command knows of a few repositories from which it can
“import” package metadata.  The result is a package definition, or a
template thereof, in the format we know (*note Defining Packages::).

   The general syntax is:

     guix import [GLOBAL-OPTIONS...] IMPORTER PACKAGE [OPTIONS...]

   IMPORTER specifies the source from which to import package metadata,
and OPTIONS specifies a package identifier and other options specific to
IMPORTER.  ‘guix import’ itself has the following GLOBAL-OPTIONS:

‘--insert=FILE’
‘-i FILE’
     Insert the package definition(s) that the IMPORTER generated into
     the specified FILE, either in alphabetical order among existing
     package definitions, or at the end of the file otherwise.

   Some of the importers rely on the ability to run the ‘gpgv’ command.
For these, GnuPG must be installed and in ‘$PATH’; run ‘guix install
gnupg’ if needed.

   Currently, the available “importers” are:

‘gnu’
     Import metadata for the given GNU package.  This provides a
     template for the latest version of that GNU package, including the
     hash of its source tarball, and its canonical synopsis and
     description.

     Additional information such as the package dependencies and its
     license needs to be figured out manually.

     For example, the following command returns a package definition for
     GNU Hello:

          guix import gnu hello

     Specific command-line options are:

     ‘--key-download=POLICY’
          As for ‘guix refresh’, specify the policy to handle missing
          OpenPGP keys when verifying the package signature.  *Note
          ‘--key-download’: Invoking guix refresh.

‘pypi’
     Import metadata from the Python Package Index
     (https://pypi.python.org/).  Information is taken from the
     JSON-formatted description available at ‘pypi.python.org’ and
     usually includes all the relevant information, including package
     dependencies.  For maximum efficiency, it is recommended to install
     the ‘unzip’ utility, so that the importer can unzip Python wheels
     and gather data from them.

     The command below imports metadata for the latest version of the
     ‘itsdangerous’ Python package:

          guix import pypi itsdangerous

     You can also ask for a specific version:

          guix import pypi itsdangerous@1.1.0

     ‘--recursive’
     ‘-r’
          Traverse the dependency graph of the given upstream package
          recursively and generate package expressions for all those
          packages that are not yet in Guix.

‘gem’
     Import metadata from RubyGems (https://rubygems.org/).  Information
     is taken from the JSON-formatted description available at
     ‘rubygems.org’ and includes most relevant information, including
     runtime dependencies.  There are some caveats, however.  The
     metadata doesn’t distinguish between synopses and descriptions, so
     the same string is used for both fields.  Additionally, the details
     of non-Ruby dependencies required to build native extensions is
     unavailable and left as an exercise to the packager.

     The command below imports metadata for the ‘rails’ Ruby package:

          guix import gem rails

     You can also ask for a specific version:

          guix import gem rails@7.0.4

     ‘--recursive’
     ‘-r’
          Traverse the dependency graph of the given upstream package
          recursively and generate package expressions for all those
          packages that are not yet in Guix.

‘minetest’
     Import metadata from ContentDB (https://content.minetest.net).
     Information is taken from the JSON-formatted metadata provided
     through ContentDB’s API (https://content.minetest.net/help/api/)
     and includes most relevant information, including dependencies.
     There are some caveats, however.  The license information is often
     incomplete.  The commit hash is sometimes missing.  The
     descriptions are in the Markdown format, but Guix uses Texinfo
     instead.  Texture packs and subgames are unsupported.

     The command below imports metadata for the Mesecons mod by Jeija:

          guix import minetest Jeija/mesecons

     The author name can also be left out:

          guix import minetest mesecons

     ‘--recursive’
     ‘-r’
          Traverse the dependency graph of the given upstream package
          recursively and generate package expressions for all those
          packages that are not yet in Guix.

‘cpan’
     Import metadata from MetaCPAN (https://www.metacpan.org/).
     Information is taken from the JSON-formatted metadata provided
     through MetaCPAN’s API (https://fastapi.metacpan.org/) and includes
     most relevant information, such as module dependencies.  License
     information should be checked closely.  If Perl is available in the
     store, then the ‘corelist’ utility will be used to filter core
     modules out of the list of dependencies.

     The command below imports metadata for the Acme::Boolean Perl
     module:

          guix import cpan Acme::Boolean

     Like many other importers, the ‘cpan’ importer supports recursive
     imports:

     ‘--recursive’
     ‘-r’
          Traverse the dependency graph of the given upstream package
          recursively and generate package expressions for all those
          packages that are not yet in Guix.

‘cran’
     Import metadata from CRAN (https://cran.r-project.org/), the
     central repository for the GNU R statistical and graphical
     environment (https://r-project.org).

     Information is extracted from the ‘DESCRIPTION’ file of the
     package.

     The command below imports metadata for the Cairo R package:

          guix import cran Cairo

     You can also ask for a specific version:

          guix import cran rasterVis@0.50.3

     When ‘--recursive’ is added, the importer will traverse the
     dependency graph of the given upstream package recursively and
     generate package expressions for all those packages that are not
     yet in Guix.

     When ‘--style=specification’ is added, the importer will generate
     package definitions whose inputs are package specifications instead
     of references to package variables.  This is useful when generated
     package definitions are to be appended to existing user modules, as
     the list of used package modules need not be changed.  The default
     is ‘--style=variable’.

     When ‘--prefix=license:’ is added, the importer will prefix license
     atoms with ‘license:’, allowing a prefixed import of ‘(guix
     licenses)’.

     When ‘--archive=bioconductor’ is added, metadata is imported from
     Bioconductor (https://www.bioconductor.org/), a repository of R
     packages for the analysis and comprehension of high-throughput
     genomic data in bioinformatics.

     Information is extracted from the ‘DESCRIPTION’ file contained in
     the package archive.

     The command below imports metadata for the GenomicRanges R package:

          guix import cran --archive=bioconductor GenomicRanges

     Finally, you can also import R packages that have not yet been
     published on CRAN or Bioconductor as long as they are in a git
     repository.  Use ‘--archive=git’ followed by the URL of the git
     repository:

          guix import cran --archive=git https://github.com/immunogenomics/harmony

‘texlive’
     Import TeX package information from the TeX Live package database
     for TeX packages that are part of the TeX Live distribution
     (https://www.tug.org/texlive/).

     Information about the package is obtained from the TeX Live package
     database, a plain text file that is included in the
     ‘texlive-scripts’ package.  The source code is downloaded from
     possibly multiple locations in the SVN repository of the Tex Live
     project.  Note that therefore SVN must be installed and in ‘$PATH’;
     run ‘guix install subversion’ if needed.

     The command below imports metadata for the ‘fontspec’ TeX package:

          guix import texlive fontspec

     Additional options include:

     ‘--recursive’
     ‘-r’
          Traverse the dependency graph of the given upstream package
          recursively and generate package expressions for all those
          packages that are not yet in Guix.

‘json’
     Import package metadata from a local JSON file.  Consider the
     following example package definition in JSON format:

          {
            "name": "hello",
            "version": "2.10",
            "source": "mirror://gnu/hello/hello-2.10.tar.gz",
            "build-system": "gnu",
            "home-page": "https://www.gnu.org/software/hello/",
            "synopsis": "Hello, GNU world: An example GNU package",
            "description": "GNU Hello prints a greeting.",
            "license": "GPL-3.0+",
            "native-inputs": ["gettext"]
          }

     The field names are the same as for the ‘<package>’ record (*Note
     Defining Packages::).  References to other packages are provided as
     JSON lists of quoted package specification strings such as ‘guile’
     or ‘guile@2.0’.

     The importer also supports a more explicit source definition using
     the common fields for ‘<origin>’ records:

          {
            ...
            "source": {
              "method": "url-fetch",
              "uri": "mirror://gnu/hello/hello-2.10.tar.gz",
              "sha256": {
                "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"
              }
            }
            ...
          }

     The command below reads metadata from the JSON file ‘hello.json’
     and outputs a package expression:

          guix import json hello.json

‘hackage’
     Import metadata from the Haskell community’s central package
     archive Hackage (https://hackage.haskell.org/).  Information is
     taken from Cabal files and includes all the relevant information,
     including package dependencies.

     Specific command-line options are:

     ‘--stdin’
     ‘-s’
          Read a Cabal file from standard input.
     ‘--no-test-dependencies’
     ‘-t’
          Do not include dependencies required only by the test suites.
     ‘--cabal-environment=ALIST’
     ‘-e ALIST’
          ALIST is a Scheme alist defining the environment in which the
          Cabal conditionals are evaluated.  The accepted keys are:
          ‘os’, ‘arch’, ‘impl’ and a string representing the name of a
          flag.  The value associated with a flag has to be either the
          symbol ‘true’ or ‘false’.  The value associated with other
          keys has to conform to the Cabal file format definition.  The
          default value associated with the keys ‘os’, ‘arch’ and ‘impl’
          is ‘linux’, ‘x86_64’ and ‘ghc’, respectively.
     ‘--recursive’
     ‘-r’
          Traverse the dependency graph of the given upstream package
          recursively and generate package expressions for all those
          packages that are not yet in Guix.

     The command below imports metadata for the latest version of the
     HTTP Haskell package without including test dependencies and
     specifying the value of the flag ‘network-uri’ as ‘false’:

          guix import hackage -t -e "'((\"network-uri\" . false))" HTTP

     A specific package version may optionally be specified by following
     the package name by an at-sign and a version number as in the
     following example:

          guix import hackage mtl@2.1.3.1

‘stackage’
     The ‘stackage’ importer is a wrapper around the ‘hackage’ one.  It
     takes a package name, looks up the package version included in a
     long-term support (LTS) Stackage (https://www.stackage.org) release
     and uses the ‘hackage’ importer to retrieve its metadata.  Note
     that it is up to you to select an LTS release compatible with the
     GHC compiler used by Guix.

     Specific command-line options are:

     ‘--no-test-dependencies’
     ‘-t’
          Do not include dependencies required only by the test suites.
     ‘--lts-version=VERSION’
     ‘-l VERSION’
          VERSION is the desired LTS release version.  If omitted the
          latest release is used.
     ‘--recursive’
     ‘-r’
          Traverse the dependency graph of the given upstream package
          recursively and generate package expressions for all those
          packages that are not yet in Guix.

     The command below imports metadata for the HTTP Haskell package
     included in the LTS Stackage release version 7.18:

          guix import stackage --lts-version=7.18 HTTP

‘elpa’
     Import metadata from an Emacs Lisp Package Archive (ELPA) package
     repository (*note (emacs)Packages::).

     Specific command-line options are:

     ‘--archive=REPO’
     ‘-a REPO’
          REPO identifies the archive repository from which to retrieve
          the information.  Currently the supported repositories and
          their identifiers are:
             - GNU (https://elpa.gnu.org/packages), selected by the
               ‘gnu’ identifier.  This is the default.

               Packages from ‘elpa.gnu.org’ are signed with one of the
               keys contained in the GnuPG keyring at
               ‘share/emacs/25.1/etc/package-keyring.gpg’ (or similar)
               in the ‘emacs’ package (*note ELPA package signatures:
               (emacs)Package Installation.).

             - NonGNU (https://elpa.nongnu.org/nongnu/), selected by the
               ‘nongnu’ identifier.

             - MELPA-Stable (https://stable.melpa.org/packages),
               selected by the ‘melpa-stable’ identifier.

             - MELPA (https://melpa.org/packages), selected by the
               ‘melpa’ identifier.

     ‘--recursive’
     ‘-r’
          Traverse the dependency graph of the given upstream package
          recursively and generate package expressions for all those
          packages that are not yet in Guix.

‘crate’
     Import metadata from the crates.io Rust package repository
     crates.io (https://crates.io), as in this example:

          guix import crate blake2-rfc

     The crate importer also allows you to specify a version string:

          guix import crate constant-time-eq@0.1.0

     Additional options include:

     ‘--allow-yanked’
          If no non-yanked version of a crate is available, use the
          latest yanked version instead instead of aborting.
     ‘--lockfile=FILE’
     ‘-f FILE’
          When ‘--lockfile’ is specified, the importer will ignore other
          options and won’t output package expressions, instead
          importing source expressions from FILE, a ‘Cargo.lock’ file.

          *Note (guix-cookbook)Packaging Rust Crates::, for packaging
          workflow utilizing it.

‘elm’
     Import metadata from the Elm package repository
     package.elm-lang.org (https://package.elm-lang.org), as in this
     example:

          guix import elm elm-explorations/webgl

     The Elm importer also allows you to specify a version string:

          guix import elm elm-explorations/webgl@1.1.3

     Additional options include:

     ‘--recursive’
     ‘-r’
          Traverse the dependency graph of the given upstream package
          recursively and generate package expressions for all those
          packages that are not yet in Guix.

‘npm-binary’
     Import metadata from the npm Registry (https://registry.npmjs.org),
     as in this example:

          guix import npm-binary buffer-crc32

     The npm-binary importer also allows you to specify a version
     string:

          guix import npm-binary buffer-crc32@1.0.0

          Note: Generated package expressions skip the build step of the
          ‘node-build-system’.  As such, generated package expressions
          often refer to transpiled or generated files, instead of being
          built from source.

     Additional options include:

     ‘--recursive’
     ‘-r’
          Traverse the dependency graph of the given upstream package
          recursively and generate package expressions for all those
          packages that are not yet in Guix.

‘opam’
     Import metadata from the OPAM (https://opam.ocaml.org/) package
     repository used by the OCaml community.

     Additional options include:

     ‘--recursive’
     ‘-r’
          Traverse the dependency graph of the given upstream package
          recursively and generate package expressions for all those
          packages that are not yet in Guix.

‘composer’
     Import metadata from the Composer (https://getcomposer.org/)
     package archive used by the PHP community, as in this example:

          guix import composer phpunit/phpunit

     Additional options include:

     ‘--recursive’
     ‘-r’
          Traverse the dependency graph of the given upstream package
          recursively and generate package expressions for all those
          packages that are not yet in Guix.
     ‘--repo’
          By default, packages are searched in the official OPAM
          repository.  This option, which can be used more than once,
          lets you add other repositories which will be searched for
          packages.  It accepts as valid arguments:

             • the name of a known repository - can be one of ‘opam’,
               ‘coq’ (equivalent to ‘coq-released’), ‘coq-core-dev’,
               ‘coq-extra-dev’ or ‘grew’.
             • the URL of a repository as expected by the ‘opam
               repository add’ command (for instance, the URL equivalent
               of the above ‘opam’ name would be
               <https://opam.ocaml.org>).
             • the path to a local copy of a repository (a directory
               containing a ‘packages/’ sub-directory).

          Repositories are assumed to be passed to this option by order
          of preference.  The additional repositories will not replace
          the default ‘opam’ repository, which is always kept as a
          fallback.

          Also, please note that versions are not compared across
          repositories.  The first repository (from left to right) that
          has at least one version of a given package will prevail over
          any others, and the version imported will be the latest one
          found _in this repository only_.

‘go’
     Import metadata for a Go module using proxy.golang.org
     (https://proxy.golang.org).

          guix import go gopkg.in/yaml.v2

     It is possible to use a package specification with a ‘@VERSION’
     suffix to import a specific version.

     Additional options include:

     ‘--recursive’
     ‘-r’
          Traverse the dependency graph of the given upstream package
          recursively and generate package expressions for all those
          packages that are not yet in Guix.
     ‘--pin-versions’
          When using this option, the importer preserves the exact
          versions of the Go modules dependencies instead of using their
          latest available versions.  This can be useful when attempting
          to import packages that recursively depend on former versions
          of themselves to build.  When using this mode, the symbol of
          the package is made by appending the version to its name, so
          that multiple versions of the same package can coexist.

‘egg’
     Import metadata for CHICKEN eggs (https://wiki.call-cc.org/eggs).
     The information is taken from ‘PACKAGE.egg’ files found in the
     eggs-5-all (git://code.call-cc.org/eggs-5-all) Git repository.
     However, it does not provide all the information that we need,
     there is no “description” field, and the licenses used are not
     always precise (BSD is often used instead of BSD-N).

          guix import egg sourcehut

     You can also ask for a specific version:

          guix import egg arrays@1.0

     Additional options include:
     ‘--recursive’
     ‘-r’
          Traverse the dependency graph of the given upstream package
          recursively and generate package expressions for all those
          packages that are not yet in Guix.

‘hexpm’
     Import metadata from the hex.pm Erlang and Elixir package
     repository hex.pm (https://hex.pm), as in this example:

          guix import hexpm stun

     The importer tries to determine the build system used by the
     package.

     The hexpm importer also allows you to specify a version string:

          guix import hexpm cf@0.3.0

     Additional options include:

     ‘--recursive’
     ‘-r’
          Traverse the dependency graph of the given upstream package
          recursively and generate package expressions for all those
          packages that are not yet in Guix.

   The structure of the ‘guix import’ code is modular.  It would be
useful to have more importers for other package formats, and your help
is welcome here (*note Contributing::).

