You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

14472 lines
542 KiB

  1. \input texinfo
  2. @c -*-texinfo-*-
  3. @c %**start of header
  4. @setfilename guix.info
  5. @documentencoding UTF-8
  6. @settitle GNU Guix Reference Manual
  7. @c %**end of header
  8. @include version.texi
  9. @c Identifier of the OpenPGP key used to sign tarballs and such.
  10. @set OPENPGP-SIGNING-KEY-ID BCA689B636553801C3C62150197A5888235FACAC
  11. @copying
  12. Copyright @copyright{} 2012, 2013, 2014, 2015, 2016 Ludovic Courtès@*
  13. Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@*
  14. Copyright @copyright{} 2013 Nikita Karetnikov@*
  15. Copyright @copyright{} 2014, 2015, 2016 Alex Kost@*
  16. Copyright @copyright{} 2015, 2016 Mathieu Lirzin@*
  17. Copyright @copyright{} 2014 Pierre-Antoine Rault@*
  18. Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
  19. Copyright @copyright{} 2015, 2016 Leo Famulari@*
  20. Copyright @copyright{} 2015, 2016 Ricardo Wurmus@*
  21. Copyright @copyright{} 2016 Ben Woodcroft@*
  22. Copyright @copyright{} 2016 Chris Marusich@*
  23. Copyright @copyright{} 2016 Efraim Flashner@*
  24. Copyright @copyright{} 2016 John Darrington@*
  25. Copyright @copyright{} 2016 ng0@*
  26. Copyright @copyright{} 2016 Jan Nieuwenhuizen@*
  27. Copyright @copyright{} 2016 Julien Lepiller@*
  28. Copyright @copyright{} 2016 Alex ter Weele
  29. Permission is granted to copy, distribute and/or modify this document
  30. under the terms of the GNU Free Documentation License, Version 1.3 or
  31. any later version published by the Free Software Foundation; with no
  32. Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
  33. copy of the license is included in the section entitled ``GNU Free
  34. Documentation License''.
  35. @end copying
  36. @dircategory System administration
  37. @direntry
  38. * Guix: (guix). Manage installed software and system configuration.
  39. * guix package: (guix)Invoking guix package. Installing, removing, and upgrading packages.
  40. * guix build: (guix)Invoking guix build. Building packages.
  41. * guix gc: (guix)Invoking guix gc. Reclaiming unused disk space.
  42. * guix pull: (guix)Invoking guix pull. Update the list of available packages.
  43. * guix system: (guix)Invoking guix system. Manage the operating system configuration.
  44. @end direntry
  45. @dircategory Software development
  46. @direntry
  47. * guix environment: (guix)Invoking guix environment. Building development environments with Guix.
  48. @end direntry
  49. @titlepage
  50. @title GNU Guix Reference Manual
  51. @subtitle Using the GNU Guix Functional Package Manager
  52. @author The GNU Guix Developers
  53. @page
  54. @vskip 0pt plus 1filll
  55. Edition @value{EDITION} @*
  56. @value{UPDATED} @*
  57. @insertcopying
  58. @end titlepage
  59. @contents
  60. @c *********************************************************************
  61. @node Top
  62. @top GNU Guix
  63. This document describes GNU Guix version @value{VERSION}, a functional
  64. package management tool written for the GNU system.
  65. @menu
  66. * Introduction:: What is Guix about?
  67. * Installation:: Installing Guix.
  68. * Package Management:: Package installation, upgrade, etc.
  69. * Programming Interface:: Using Guix in Scheme.
  70. * Utilities:: Package management commands.
  71. * GNU Distribution:: Software for your friendly GNU system.
  72. * Contributing:: Your help needed!
  73. * Acknowledgments:: Thanks!
  74. * GNU Free Documentation License:: The license of this manual.
  75. * Concept Index:: Concepts.
  76. * Programming Index:: Data types, functions, and variables.
  77. @detailmenu
  78. --- The Detailed Node Listing ---
  79. Installation
  80. * Binary Installation:: Getting Guix running in no time!
  81. * Requirements:: Software needed to build and run Guix.
  82. * Running the Test Suite:: Testing Guix.
  83. * Setting Up the Daemon:: Preparing the build daemon's environment.
  84. * Invoking guix-daemon:: Running the build daemon.
  85. * Application Setup:: Application-specific setup.
  86. Setting Up the Daemon
  87. * Build Environment Setup:: Preparing the isolated build environment.
  88. * Daemon Offload Setup:: Offloading builds to remote machines.
  89. Package Management
  90. * Features:: How Guix will make your life brighter.
  91. * Invoking guix package:: Package installation, removal, etc.
  92. * Substitutes:: Downloading pre-built binaries.
  93. * Packages with Multiple Outputs:: Single source package, multiple outputs.
  94. * Invoking guix gc:: Running the garbage collector.
  95. * Invoking guix pull:: Fetching the latest Guix and distribution.
  96. * Invoking guix archive:: Exporting and importing store files.
  97. Programming Interface
  98. * Defining Packages:: Defining new packages.
  99. * Build Systems:: Specifying how packages are built.
  100. * The Store:: Manipulating the package store.
  101. * Derivations:: Low-level interface to package derivations.
  102. * The Store Monad:: Purely functional interface to the store.
  103. * G-Expressions:: Manipulating build expressions.
  104. Defining Packages
  105. * package Reference:: The package data type.
  106. * origin Reference:: The origin data type.
  107. Utilities
  108. * Invoking guix build:: Building packages from the command line.
  109. * Invoking guix edit:: Editing package definitions.
  110. * Invoking guix download:: Downloading a file and printing its hash.
  111. * Invoking guix hash:: Computing the cryptographic hash of a file.
  112. * Invoking guix import:: Importing package definitions.
  113. * Invoking guix refresh:: Updating package definitions.
  114. * Invoking guix lint:: Finding errors in package definitions.
  115. * Invoking guix size:: Profiling disk usage.
  116. * Invoking guix graph:: Visualizing the graph of packages.
  117. * Invoking guix environment:: Setting up development environments.
  118. * Invoking guix publish:: Sharing substitutes.
  119. * Invoking guix challenge:: Challenging substitute servers.
  120. * Invoking guix container:: Process isolation.
  121. Invoking @command{guix build}
  122. * Common Build Options:: Build options for most commands.
  123. * Package Transformation Options:: Creating variants of packages.
  124. * Additional Build Options:: Options specific to 'guix build'.
  125. GNU Distribution
  126. * System Installation:: Installing the whole operating system.
  127. * System Configuration:: Configuring the operating system.
  128. * Installing Debugging Files:: Feeding the debugger.
  129. * Security Updates:: Deploying security fixes quickly.
  130. * Package Modules:: Packages from the programmer's viewpoint.
  131. * Packaging Guidelines:: Growing the distribution.
  132. * Bootstrapping:: GNU/Linux built from scratch.
  133. * Porting:: Targeting another platform or kernel.
  134. System Installation
  135. * Limitations:: What you can expect.
  136. * Hardware Considerations:: Supported hardware.
  137. * USB Stick Installation:: Preparing the installation medium.
  138. * Preparing for Installation:: Networking, partitioning, etc.
  139. * Proceeding with the Installation:: The real thing.
  140. * Installing GuixSD in a VM:: GuixSD playground.
  141. * Building the Installation Image:: How this comes to be.
  142. System Configuration
  143. * Using the Configuration System:: Customizing your GNU system.
  144. * operating-system Reference:: Detail of operating-system declarations.
  145. * File Systems:: Configuring file system mounts.
  146. * Mapped Devices:: Block device extra processing.
  147. * User Accounts:: Specifying user accounts.
  148. * Locales:: Language and cultural convention settings.
  149. * Services:: Specifying system services.
  150. * Setuid Programs:: Programs running with root privileges.
  151. * X.509 Certificates:: Authenticating HTTPS servers.
  152. * Name Service Switch:: Configuring libc's name service switch.
  153. * Initial RAM Disk:: Linux-Libre bootstrapping.
  154. * GRUB Configuration:: Configuring the boot loader.
  155. * Invoking guix system:: Instantiating a system configuration.
  156. * Running GuixSD in a VM:: How to run GuixSD in a virtual machine.
  157. * Defining Services:: Adding new service definitions.
  158. Services
  159. * Base Services:: Essential system services.
  160. * Scheduled Job Execution:: The mcron service.
  161. * Log Rotation:: The rottlog service.
  162. * Networking Services:: Network setup, SSH daemon, etc.
  163. * X Window:: Graphical display.
  164. * Desktop Services:: D-Bus and desktop services.
  165. * Database Services:: SQL databases.
  166. * Mail Services:: IMAP, POP3, SMTP, and all that.
  167. * Kerberos Services:: Kerberos services.
  168. * Web Services:: Web servers.
  169. * Network File System:: NFS related services.
  170. * Miscellaneous Services:: Other services.
  171. Defining Services
  172. * Service Composition:: The model for composing services.
  173. * Service Types and Services:: Types and services.
  174. * Service Reference:: API reference.
  175. * Shepherd Services:: A particular type of service.
  176. Packaging Guidelines
  177. * Software Freedom:: What may go into the distribution.
  178. * Package Naming:: What's in a name?
  179. * Version Numbers:: When the name is not enough.
  180. * Synopses and Descriptions:: Helping users find the right package.
  181. * Python Modules:: Taming the snake.
  182. * Perl Modules:: Little pearls.
  183. * Java Packages:: Coffee break.
  184. * Fonts:: Fond of fonts.
  185. Contributing
  186. * Building from Git:: The latest and greatest.
  187. * Running Guix Before It Is Installed:: Hacker tricks.
  188. * The Perfect Setup:: The right tools.
  189. * Coding Style:: Hygiene of the contributor.
  190. * Submitting Patches:: Share your work.
  191. Coding Style
  192. * Programming Paradigm:: How to compose your elements.
  193. * Modules:: Where to store your code?
  194. * Data Types and Pattern Matching:: Implementing data structures.
  195. * Formatting Code:: Writing conventions.
  196. @end detailmenu
  197. @end menu
  198. @c *********************************************************************
  199. @node Introduction
  200. @chapter Introduction
  201. @cindex purpose
  202. GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
  203. using the international phonetic alphabet (IPA).} is a package
  204. management tool for the GNU system. Guix makes it easy for unprivileged
  205. users to install, upgrade, or remove packages, to roll back to a
  206. previous package set, to build packages from source, and generally
  207. assists with the creation and maintenance of software environments.
  208. @cindex user interfaces
  209. Guix provides a command-line package management interface
  210. (@pxref{Invoking guix package}), a set of command-line utilities
  211. (@pxref{Utilities}), as well as Scheme programming interfaces
  212. (@pxref{Programming Interface}).
  213. @cindex build daemon
  214. Its @dfn{build daemon} is responsible for building packages on behalf of
  215. users (@pxref{Setting Up the Daemon}) and for downloading pre-built
  216. binaries from authorized sources (@pxref{Substitutes}).
  217. @cindex extensibility of the distribution
  218. @cindex customization, of packages
  219. Guix includes package definitions for many GNU and non-GNU packages, all
  220. of which @uref{https://www.gnu.org/philosophy/free-sw.html, respect the
  221. user's computing freedom}. It is @emph{extensible}: users can write
  222. their own package definitions (@pxref{Defining Packages}) and make them
  223. available as independent package modules (@pxref{Package Modules}). It
  224. is also @emph{customizable}: users can @emph{derive} specialized package
  225. definitions from existing ones, including from the command line
  226. (@pxref{Package Transformation Options}).
  227. @cindex Guix System Distribution
  228. @cindex GuixSD
  229. You can install GNU@tie{}Guix on top of an existing GNU/Linux system
  230. where it complements the available tools without interference
  231. (@pxref{Installation}), or you can use it as part of the standalone
  232. @dfn{Guix System Distribution} or GuixSD (@pxref{GNU Distribution}).
  233. With GNU@tie{}GuixSD, you @emph{declare} all aspects of the operating
  234. system configuration and Guix takes care of instantiating the
  235. configuration in a transactional, reproducible, and stateless fashion
  236. (@pxref{System Configuration}).
  237. @cindex functional package management
  238. Under the hood, Guix implements the @dfn{functional package management}
  239. discipline pioneered by Nix (@pxref{Acknowledgments}).
  240. In Guix, the package build and installation process is seen
  241. as a @emph{function}, in the mathematical sense. That function takes inputs,
  242. such as build scripts, a compiler, and libraries, and
  243. returns an installed package. As a pure function, its result depends
  244. solely on its inputs---for instance, it cannot refer to software or
  245. scripts that were not explicitly passed as inputs. A build function
  246. always produces the same result when passed a given set of inputs. It
  247. cannot alter the environment of the running system in
  248. any way; for instance, it cannot create, modify, or delete files outside
  249. of its build and installation directories. This is achieved by running
  250. build processes in isolated environments (or @dfn{containers}), where only their
  251. explicit inputs are visible.
  252. @cindex store
  253. The result of package build functions is @dfn{cached} in the file
  254. system, in a special directory called @dfn{the store} (@pxref{The
  255. Store}). Each package is installed in a directory of its own in the
  256. store---by default under @file{/gnu/store}. The directory name contains
  257. a hash of all the inputs used to build that package; thus, changing an
  258. input yields a different directory name.
  259. This approach is the foundation for the salient features of Guix: support
  260. for transactional package upgrade and rollback, per-user installation, and
  261. garbage collection of packages (@pxref{Features}).
  262. @c *********************************************************************
  263. @node Installation
  264. @chapter Installation
  265. @cindex installing Guix
  266. GNU Guix is available for download from its website at
  267. @url{http://www.gnu.org/software/guix/}. This section describes the
  268. software requirements of Guix, as well as how to install it and get
  269. ready to use it.
  270. Note that this section is concerned with the installation of the package
  271. manager, which can be done on top of a running GNU/Linux system. If,
  272. instead, you want to install the complete GNU operating system,
  273. @pxref{System Installation}.
  274. @cindex foreign distro
  275. When installed on a running GNU/Linux system---thereafter called a
  276. @dfn{foreign distro}---GNU@tie{}Guix complements the available tools
  277. without interference. Its data lives exclusively in two directories,
  278. usually @file{/gnu/store} and @file{/var/guix}; other files on your
  279. system, such as @file{/etc}, are left untouched.
  280. Once installed, Guix can be updated by running @command{guix pull}
  281. (@pxref{Invoking guix pull}).
  282. @menu
  283. * Binary Installation:: Getting Guix running in no time!
  284. * Requirements:: Software needed to build and run Guix.
  285. * Running the Test Suite:: Testing Guix.
  286. * Setting Up the Daemon:: Preparing the build daemon's environment.
  287. * Invoking guix-daemon:: Running the build daemon.
  288. * Application Setup:: Application-specific setup.
  289. @end menu
  290. @node Binary Installation
  291. @section Binary Installation
  292. @cindex installing Guix from binaries
  293. This section describes how to install Guix on an arbitrary system from a
  294. self-contained tarball providing binaries for Guix and for all its
  295. dependencies. This is often quicker than installing from source, which
  296. is described in the next sections. The only requirement is to have
  297. GNU@tie{}tar and Xz.
  298. Installing goes along these lines:
  299. @enumerate
  300. @item
  301. @cindex downloading Guix binary
  302. Download the binary tarball from
  303. @indicateurl{ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz},
  304. where @var{system} is @code{x86_64-linux} for an @code{x86_64} machine
  305. already running the kernel Linux, and so on.
  306. @c The following is somewhat duplicated in ``System Installation''.
  307. Make sure to download the associated @file{.sig} file and to verify the
  308. authenticity of the tarball against it, along these lines:
  309. @example
  310. $ wget ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
  311. $ gpg --verify guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
  312. @end example
  313. If that command fails because you do not have the required public key,
  314. then run this command to import it:
  315. @example
  316. $ gpg --keyserver pgp.mit.edu --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
  317. @end example
  318. @noindent
  319. and rerun the @code{gpg --verify} command.
  320. @c end authentication part
  321. @item
  322. As @code{root}, run:
  323. @example
  324. # cd /tmp
  325. # tar --warning=no-timestamp -xf \
  326. guix-binary-@value{VERSION}.@var{system}.tar.xz
  327. # mv var/guix /var/ && mv gnu /
  328. @end example
  329. This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}.
  330. The latter contains a ready-to-use profile for @code{root} (see next
  331. step.)
  332. Do @emph{not} unpack the tarball on a working Guix system since that
  333. would overwrite its own essential files.
  334. The @code{--warning=no-timestamp} option makes sure GNU@tie{}tar does
  335. not emit warnings about ``implausibly old time stamps'' (such
  336. warnings were triggered by GNU@tie{}tar 1.26 and older; recent
  337. versions are fine.)
  338. They stem from the fact that all the
  339. files in the archive have their modification time set to zero (which
  340. means January 1st, 1970.) This is done on purpose to make sure the
  341. archive content is independent of its creation time, thus making it
  342. reproducible.
  343. @item
  344. Make @code{root}'s profile available under @file{~/.guix-profile}:
  345. @example
  346. # ln -sf /var/guix/profiles/per-user/root/guix-profile \
  347. ~root/.guix-profile
  348. @end example
  349. @item
  350. Create the group and user accounts for build users as explained below
  351. (@pxref{Build Environment Setup}).
  352. @item
  353. Run the daemon, and set it to automatically start on boot.
  354. If your host distro uses the systemd init system, this can be achieved
  355. with these commands:
  356. @example
  357. # ln -s ~root/.guix-profile/lib/systemd/system/guix-daemon.service \
  358. /etc/systemd/system/
  359. # systemctl start guix-daemon && systemctl enable guix-daemon
  360. @end example
  361. If your host distro uses the Upstart init system:
  362. @example
  363. # ln -s ~root/.guix-profile/lib/upstart/system/guix-daemon.conf /etc/init/
  364. # start guix-daemon
  365. @end example
  366. Otherwise, you can still start the daemon manually with:
  367. @example
  368. # ~root/.guix-profile/bin/guix-daemon --build-users-group=guixbuild
  369. @end example
  370. @item
  371. Make the @command{guix} command available to other users on the machine,
  372. for instance with:
  373. @example
  374. # mkdir -p /usr/local/bin
  375. # cd /usr/local/bin
  376. # ln -s /var/guix/profiles/per-user/root/guix-profile/bin/guix
  377. @end example
  378. It is also a good idea to make the Info version of this manual available
  379. there:
  380. @example
  381. # mkdir -p /usr/local/share/info
  382. # cd /usr/local/share/info
  383. # for i in /var/guix/profiles/per-user/root/guix-profile/share/info/* ;
  384. do ln -s $i ; done
  385. @end example
  386. That way, assuming @file{/usr/local/share/info} is in the search path,
  387. running @command{info guix} will open this manual (@pxref{Other Info
  388. Directories,,, texinfo, GNU Texinfo}, for more details on changing the
  389. Info search path.)
  390. @item
  391. @cindex substitutes, authorization thereof
  392. To use substitutes from @code{hydra.gnu.org} or one of its mirrors
  393. (@pxref{Substitutes}), authorize them:
  394. @example
  395. # guix archive --authorize < ~root/.guix-profile/share/guix/hydra.gnu.org.pub
  396. @end example
  397. @end enumerate
  398. This completes root-level install of Guix. Each user will need to
  399. perform additional steps to make their Guix environment ready for use,
  400. @pxref{Application Setup}.
  401. You can confirm that Guix is working by installing a sample package into
  402. the root profile:
  403. @example
  404. # guix package -i hello
  405. @end example
  406. The @code{guix} package must remain available in @code{root}'s profile,
  407. or it would become subject to garbage collection---in which case you
  408. would find yourself badly handicapped by the lack of the @command{guix}
  409. command. In other words, do not remove @code{guix} by running
  410. @code{guix package -r guix}.
  411. The binary installation tarball can be (re)produced and verified simply
  412. by running the following command in the Guix source tree:
  413. @example
  414. make guix-binary.@var{system}.tar.xz
  415. @end example
  416. @node Requirements
  417. @section Requirements
  418. This section lists requirements when building Guix from source. The
  419. build procedure for Guix is the same as for other GNU software, and is
  420. not covered here. Please see the files @file{README} and @file{INSTALL}
  421. in the Guix source tree for additional details.
  422. GNU Guix depends on the following packages:
  423. @itemize
  424. @item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.7 or later;
  425. @item @url{http://gnupg.org/, GNU libgcrypt};
  426. @item @url{http://www.gnu.org/software/make/, GNU Make}.
  427. @end itemize
  428. The following dependencies are optional:
  429. @itemize
  430. @item
  431. Installing @uref{http://gnutls.org/, GnuTLS-Guile} will allow you to
  432. access @code{https} URLs for substitutes, which is highly recommended
  433. (@pxref{Substitutes}). It also allows you to access HTTPS URLs with the
  434. @command{guix download} command (@pxref{Invoking guix download}), the
  435. @command{guix import pypi} command, and the @command{guix import cpan}
  436. command. @xref{Guile Preparations, how to install the GnuTLS bindings
  437. for Guile,, gnutls-guile, GnuTLS-Guile}.
  438. @item
  439. Installing
  440. @url{http://savannah.nongnu.org/projects/guile-json/, Guile-JSON} will
  441. allow you to use the @command{guix import pypi} command (@pxref{Invoking
  442. guix import}). It is of
  443. interest primarily for developers and not for casual users.
  444. @item
  445. @c Note: We need at least 0.10.2 for 'channel-send-eof'.
  446. Support for build offloading (@pxref{Daemon Offload Setup}) depends on
  447. @uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH},
  448. version 0.10.2 or later.
  449. @item
  450. When @url{http://zlib.net, zlib} is available, @command{guix publish}
  451. can compress build byproducts (@pxref{Invoking guix publish}).
  452. @end itemize
  453. Unless @code{--disable-daemon} was passed to @command{configure}, the
  454. following packages are also needed:
  455. @itemize
  456. @item @url{http://sqlite.org, SQLite 3};
  457. @item @url{http://www.bzip.org, libbz2};
  458. @item @url{http://gcc.gnu.org, GCC's g++}, with support for the
  459. C++11 standard.
  460. @end itemize
  461. @cindex state directory
  462. When configuring Guix on a system that already has a Guix installation,
  463. be sure to specify the same state directory as the existing installation
  464. using the @code{--localstatedir} option of the @command{configure}
  465. script (@pxref{Directory Variables, @code{localstatedir},, standards,
  466. GNU Coding Standards}). The @command{configure} script protects against
  467. unintended misconfiguration of @var{localstatedir} so you do not
  468. inadvertently corrupt your store (@pxref{The Store}).
  469. @cindex Nix, compatibility
  470. When a working installation of @url{http://nixos.org/nix/, the Nix package
  471. manager} is available, you
  472. can instead configure Guix with @code{--disable-daemon}. In that case,
  473. Nix replaces the three dependencies above.
  474. Guix is compatible with Nix, so it is possible to share the same store
  475. between both. To do so, you must pass @command{configure} not only the
  476. same @code{--with-store-dir} value, but also the same
  477. @code{--localstatedir} value. The latter is essential because it
  478. specifies where the database that stores metadata about the store is
  479. located, among other things. The default values for Nix are
  480. @code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
  481. Note that @code{--disable-daemon} is not required if
  482. your goal is to share the store with Nix.
  483. @node Running the Test Suite
  484. @section Running the Test Suite
  485. @cindex test suite
  486. After a successful @command{configure} and @code{make} run, it is a good
  487. idea to run the test suite. It can help catch issues with the setup or
  488. environment, or bugs in Guix itself---and really, reporting test
  489. failures is a good way to help improve the software. To run the test
  490. suite, type:
  491. @example
  492. make check
  493. @end example
  494. Test cases can run in parallel: you can use the @code{-j} option of
  495. GNU@tie{}make to speed things up. The first run may take a few minutes
  496. on a recent machine; subsequent runs will be faster because the store
  497. that is created for test purposes will already have various things in
  498. cache.
  499. It is also possible to run a subset of the tests by defining the
  500. @code{TESTS} makefile variable as in this example:
  501. @example
  502. make check TESTS="tests/store.scm tests/cpio.scm"
  503. @end example
  504. By default, tests results are displayed at a file level. In order to
  505. see the details of every individual test cases, it is possible to define
  506. the @code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example:
  507. @example
  508. make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"
  509. @end example
  510. Upon failure, please email @email{bug-guix@@gnu.org} and attach the
  511. @file{test-suite.log} file. Please specify the Guix version being used
  512. as well as version numbers of the dependencies (@pxref{Requirements}) in
  513. your message.
  514. Guix also comes with a whole-system test suite that tests complete
  515. GuixSD operating system instances. It can only run on systems where
  516. Guix is already installed, using:
  517. @example
  518. make check-system
  519. @end example
  520. @noindent
  521. or, again, by defining @code{TESTS} to select a subset of tests to run:
  522. @example
  523. make check-system TESTS="basic mcron"
  524. @end example
  525. These system tests are defined in the @code{(gnu tests @dots{})}
  526. modules. They work by running the operating systems under test with
  527. lightweight instrumentation in a virtual machine (VM). They can be
  528. computationally intensive or rather cheap, depending on whether
  529. substitutes are available for their dependencies (@pxref{Substitutes}).
  530. Some of them require a lot of storage space to hold VM images.
  531. Again in case of test failures, please send @email{bug-guix@@gnu.org}
  532. all the details.
  533. @node Setting Up the Daemon
  534. @section Setting Up the Daemon
  535. @cindex daemon
  536. Operations such as building a package or running the garbage collector
  537. are all performed by a specialized process, the @dfn{build daemon}, on
  538. behalf of clients. Only the daemon may access the store and its
  539. associated database. Thus, any operation that manipulates the store
  540. goes through the daemon. For instance, command-line tools such as
  541. @command{guix package} and @command{guix build} communicate with the
  542. daemon (@i{via} remote procedure calls) to instruct it what to do.
  543. The following sections explain how to prepare the build daemon's
  544. environment. See also @ref{Substitutes}, for information on how to allow
  545. the daemon to download pre-built binaries.
  546. @menu
  547. * Build Environment Setup:: Preparing the isolated build environment.
  548. * Daemon Offload Setup:: Offloading builds to remote machines.
  549. @end menu
  550. @node Build Environment Setup
  551. @subsection Build Environment Setup
  552. @cindex build environment
  553. In a standard multi-user setup, Guix and its daemon---the
  554. @command{guix-daemon} program---are installed by the system
  555. administrator; @file{/gnu/store} is owned by @code{root} and
  556. @command{guix-daemon} runs as @code{root}. Unprivileged users may use
  557. Guix tools to build packages or otherwise access the store, and the
  558. daemon will do it on their behalf, ensuring that the store is kept in a
  559. consistent state, and allowing built packages to be shared among users.
  560. @cindex build users
  561. When @command{guix-daemon} runs as @code{root}, you may not want package
  562. build processes themselves to run as @code{root} too, for obvious
  563. security reasons. To avoid that, a special pool of @dfn{build users}
  564. should be created for use by build processes started by the daemon.
  565. These build users need not have a shell and a home directory: they will
  566. just be used when the daemon drops @code{root} privileges in build
  567. processes. Having several such users allows the daemon to launch
  568. distinct build processes under separate UIDs, which guarantees that they
  569. do not interfere with each other---an essential feature since builds are
  570. regarded as pure functions (@pxref{Introduction}).
  571. On a GNU/Linux system, a build user pool may be created like this (using
  572. Bash syntax and the @code{shadow} commands):
  573. @c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
  574. @c for why `-G' is needed.
  575. @example
  576. # groupadd --system guixbuild
  577. # for i in `seq -w 1 10`;
  578. do
  579. useradd -g guixbuild -G guixbuild \
  580. -d /var/empty -s `which nologin` \
  581. -c "Guix build user $i" --system \
  582. guixbuilder$i;
  583. done
  584. @end example
  585. @noindent
  586. The number of build users determines how many build jobs may run in
  587. parallel, as specified by the @option{--max-jobs} option
  588. (@pxref{Invoking guix-daemon, @option{--max-jobs}}). To use
  589. @command{guix system vm} and related commands, you may need to add the
  590. build users to the @code{kvm} group so they can access @file{/dev/kvm},
  591. using @code{-G guixbuild,kvm} instead of @code{-G guixbuild}
  592. (@pxref{Invoking guix system}).
  593. The @code{guix-daemon} program may then be run as @code{root} with the
  594. following command@footnote{If your machine uses the systemd init system,
  595. dropping the @file{@var{prefix}/lib/systemd/system/guix-daemon.service}
  596. file in @file{/etc/systemd/system} will ensure that
  597. @command{guix-daemon} is automatically started. Similarly, if your
  598. machine uses the Upstart init system, drop the
  599. @file{@var{prefix}/lib/upstart/system/guix-daemon.conf}
  600. file in @file{/etc/init}.}:
  601. @example
  602. # guix-daemon --build-users-group=guixbuild
  603. @end example
  604. @cindex chroot
  605. @noindent
  606. This way, the daemon starts build processes in a chroot, under one of
  607. the @code{guixbuilder} users. On GNU/Linux, by default, the chroot
  608. environment contains nothing but:
  609. @c Keep this list in sync with libstore/build.cc! -----------------------
  610. @itemize
  611. @item
  612. a minimal @code{/dev} directory, created mostly independently from the
  613. host @code{/dev}@footnote{``Mostly'', because while the set of files
  614. that appear in the chroot's @code{/dev} is fixed, most of these files
  615. can only be created if the host has them.};
  616. @item
  617. the @code{/proc} directory; it only shows the processes of the container
  618. since a separate PID name space is used;
  619. @item
  620. @file{/etc/passwd} with an entry for the current user and an entry for
  621. user @file{nobody};
  622. @item
  623. @file{/etc/group} with an entry for the user's group;
  624. @item
  625. @file{/etc/hosts} with an entry that maps @code{localhost} to
  626. @code{127.0.0.1};
  627. @item
  628. a writable @file{/tmp} directory.
  629. @end itemize
  630. You can influence the directory where the daemon stores build trees
  631. @i{via} the @code{TMPDIR} environment variable. However, the build tree
  632. within the chroot is always called @file{/tmp/guix-build-@var{name}.drv-0},
  633. where @var{name} is the derivation name---e.g., @code{coreutils-8.24}.
  634. This way, the value of @code{TMPDIR} does not leak inside build
  635. environments, which avoids discrepancies in cases where build processes
  636. capture the name of their build tree.
  637. @vindex http_proxy
  638. The daemon also honors the @code{http_proxy} environment variable for
  639. HTTP downloads it performs, be it for fixed-output derivations
  640. (@pxref{Derivations}) or for substitutes (@pxref{Substitutes}).
  641. If you are installing Guix as an unprivileged user, it is still possible
  642. to run @command{guix-daemon} provided you pass @code{--disable-chroot}.
  643. However, build processes will not be isolated from one another, and not
  644. from the rest of the system. Thus, build processes may interfere with
  645. each other, and may access programs, libraries, and other files
  646. available on the system---making it much harder to view them as
  647. @emph{pure} functions.
  648. @node Daemon Offload Setup
  649. @subsection Using the Offload Facility
  650. @cindex offloading
  651. @cindex build hook
  652. When desired, the build daemon can @dfn{offload} derivation builds to
  653. other machines running Guix, using the @code{offload} @dfn{build
  654. hook}@footnote{This feature is available only when
  655. @uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH} is
  656. present.}. When that
  657. feature is enabled, a list of user-specified build machines is read from
  658. @file{/etc/guix/machines.scm}; every time a build is requested, for
  659. instance via @code{guix build}, the daemon attempts to offload it to one
  660. of the machines that satisfy the constraints of the derivation, in
  661. particular its system type---e.g., @file{x86_64-linux}. Missing
  662. prerequisites for the build are copied over SSH to the target machine,
  663. which then proceeds with the build; upon success the output(s) of the
  664. build are copied back to the initial machine.
  665. The @file{/etc/guix/machines.scm} file typically looks like this:
  666. @example
  667. (list (build-machine
  668. (name "eightysix.example.org")
  669. (system "x86_64-linux")
  670. (host-key "ssh-ed25519 AAAAC3Nza@dots{}")
  671. (user "bob")
  672. (speed 2.)) ;incredibly fast!
  673. (build-machine
  674. (name "meeps.example.org")
  675. (system "mips64el-linux")
  676. (host-key "ssh-rsa AAAAB3Nza@dots{}")
  677. (user "alice")
  678. (private-key
  679. (string-append (getenv "HOME")
  680. "/.ssh/identity-for-guix"))))
  681. @end example
  682. @noindent
  683. In the example above we specify a list of two build machines, one for
  684. the @code{x86_64} architecture and one for the @code{mips64el}
  685. architecture.
  686. In fact, this file is---not surprisingly!---a Scheme file that is
  687. evaluated when the @code{offload} hook is started. Its return value
  688. must be a list of @code{build-machine} objects. While this example
  689. shows a fixed list of build machines, one could imagine, say, using
  690. DNS-SD to return a list of potential build machines discovered in the
  691. local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
  692. Avahi in Guile Scheme Programs}). The @code{build-machine} data type is
  693. detailed below.
  694. @deftp {Data Type} build-machine
  695. This data type represents build machines to which the daemon may offload
  696. builds. The important fields are:
  697. @table @code
  698. @item name
  699. The host name of the remote machine.
  700. @item system
  701. The system type of the remote machine---e.g., @code{"x86_64-linux"}.
  702. @item user
  703. The user account to use when connecting to the remote machine over SSH.
  704. Note that the SSH key pair must @emph{not} be passphrase-protected, to
  705. allow non-interactive logins.
  706. @item host-key
  707. This must be the machine's SSH @dfn{public host key} in OpenSSH format.
  708. This is used to authenticate the machine when we connect to it. It is a
  709. long string that looks like this:
  710. @example
  711. ssh-ed25519 AAAAC3NzaC@dots{}mde+UhL hint@@example.org
  712. @end example
  713. If the machine is running the OpenSSH daemon, @command{sshd}, the host
  714. key can be found in a file such as
  715. @file{/etc/ssh/ssh_host_ed25519_key.pub}.
  716. If the machine is running the SSH daemon of GNU@tie{}lsh,
  717. @command{lshd}, the host key is in @file{/etc/lsh/host-key.pub} or a
  718. similar file. It can be converted to the OpenSSH format using
  719. @command{lsh-export-key} (@pxref{Converting keys,,, lsh, LSH Manual}):
  720. @example
  721. $ lsh-export-key --openssh < /etc/lsh/host-key.pub
  722. ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV@dots{}
  723. @end example
  724. @end table
  725. A number of optional fields may be specified:
  726. @table @asis
  727. @item @code{port} (default: @code{22})
  728. Port number of SSH server on the machine.
  729. @item @code{private-key} (default: @file{~/.ssh/id_rsa})
  730. The SSH private key file to use when connecting to the machine, in
  731. OpenSSH format.
  732. @item @code{compression} (default: @code{"zlib@@openssh.com,zlib"})
  733. @itemx @code{compression-level} (default: @code{3})
  734. The SSH-level compression methods and compression level requested.
  735. Note that offloading relies on SSH compression to reduce bandwidth usage
  736. when transferring files to and from build machines.
  737. @item @code{daemon-socket} (default: @code{"/var/guix/daemon-socket/socket"})
  738. File name of the Unix-domain socket @command{guix-daemon} is listening
  739. to on that machine.
  740. @item @code{parallel-builds} (default: @code{1})
  741. The number of builds that may run in parallel on the machine.
  742. @item @code{speed} (default: @code{1.0})
  743. A ``relative speed factor''. The offload scheduler will tend to prefer
  744. machines with a higher speed factor.
  745. @item @code{features} (default: @code{'()})
  746. A list of strings denoting specific features supported by the machine.
  747. An example is @code{"kvm"} for machines that have the KVM Linux modules
  748. and corresponding hardware support. Derivations can request features by
  749. name, and they will be scheduled on matching build machines.
  750. @end table
  751. @end deftp
  752. The @code{guile} command must be in the search path on the build
  753. machines. In addition, the Guix modules must be in
  754. @code{$GUILE_LOAD_PATH} on the build machine---you can check whether
  755. this is the case by running:
  756. @example
  757. ssh build-machine guile -c "'(use-modules (guix config))'"
  758. @end example
  759. There is one last thing to do once @file{machines.scm} is in place. As
  760. explained above, when offloading, files are transferred back and forth
  761. between the machine stores. For this to work, you first need to
  762. generate a key pair on each machine to allow the daemon to export signed
  763. archives of files from the store (@pxref{Invoking guix archive}):
  764. @example
  765. # guix archive --generate-key
  766. @end example
  767. @noindent
  768. Each build machine must authorize the key of the master machine so that
  769. it accepts store items it receives from the master:
  770. @example
  771. # guix archive --authorize < master-public-key.txt
  772. @end example
  773. @noindent
  774. Likewise, the master machine must authorize the key of each build machine.
  775. All the fuss with keys is here to express pairwise mutual trust
  776. relations between the master and the build machines. Concretely, when
  777. the master receives files from a build machine (and @i{vice versa}), its
  778. build daemon can make sure they are genuine, have not been tampered
  779. with, and that they are signed by an authorized key.
  780. @cindex offload test
  781. To test whether your setup is operational, run this command on the
  782. master node:
  783. @example
  784. # guix offload test
  785. @end example
  786. This will attempt to connect to each of the build machines specified in
  787. @file{/etc/guix/machines.scm}, make sure Guile and the Guix modules are
  788. available on each machine, attempt to export to the machine and import
  789. from it, and report any error in the process.
  790. If you want to test a different machine file, just specify it on the
  791. command line:
  792. @example
  793. # guix offload test machines-qualif.scm
  794. @end example
  795. Last, you can test the subset of the machines whose name matches a
  796. regular expression like this:
  797. @example
  798. # guix offload test machines.scm '\.gnu\.org$'
  799. @end example
  800. @node Invoking guix-daemon
  801. @section Invoking @command{guix-daemon}
  802. The @command{guix-daemon} program implements all the functionality to
  803. access the store. This includes launching build processes, running the
  804. garbage collector, querying the availability of a build result, etc. It
  805. is normally run as @code{root} like this:
  806. @example
  807. # guix-daemon --build-users-group=guixbuild
  808. @end example
  809. @noindent
  810. For details on how to set it up, @pxref{Setting Up the Daemon}.
  811. @cindex chroot
  812. @cindex container, build environment
  813. @cindex build environment
  814. @cindex reproducible builds
  815. By default, @command{guix-daemon} launches build processes under
  816. different UIDs, taken from the build group specified with
  817. @code{--build-users-group}. In addition, each build process is run in a
  818. chroot environment that only contains the subset of the store that the
  819. build process depends on, as specified by its derivation
  820. (@pxref{Programming Interface, derivation}), plus a set of specific
  821. system directories. By default, the latter contains @file{/dev} and
  822. @file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
  823. @dfn{container}: in addition to having its own file system tree, it has
  824. a separate mount name space, its own PID name space, network name space,
  825. etc. This helps achieve reproducible builds (@pxref{Features}).
  826. When the daemon performs a build on behalf of the user, it creates a
  827. build directory under @file{/tmp} or under the directory specified by
  828. its @code{TMPDIR} environment variable; this directory is shared with
  829. the container for the duration of the build. Be aware that using a
  830. directory other than @file{/tmp} can affect build results---for example,
  831. with a longer directory name, a build process that uses Unix-domain
  832. sockets might hit the name length limitation for @code{sun_path}, which
  833. it would otherwise not hit.
  834. The build directory is automatically deleted upon completion, unless the
  835. build failed and the client specified @option{--keep-failed}
  836. (@pxref{Invoking guix build, @option{--keep-failed}}).
  837. The following command-line options are supported:
  838. @table @code
  839. @item --build-users-group=@var{group}
  840. Take users from @var{group} to run build processes (@pxref{Setting Up
  841. the Daemon, build users}).
  842. @item --no-substitutes
  843. @cindex substitutes
  844. Do not use substitutes for build products. That is, always build things
  845. locally instead of allowing downloads of pre-built binaries
  846. (@pxref{Substitutes}).
  847. By default substitutes are used, unless the client---such as the
  848. @command{guix package} command---is explicitly invoked with
  849. @code{--no-substitutes}.
  850. When the daemon runs with @code{--no-substitutes}, clients can still
  851. explicitly enable substitution @i{via} the @code{set-build-options}
  852. remote procedure call (@pxref{The Store}).
  853. @item --substitute-urls=@var{urls}
  854. @anchor{daemon-substitute-urls}
  855. Consider @var{urls} the default whitespace-separated list of substitute
  856. source URLs. When this option is omitted,
  857. @indicateurl{https://mirror.hydra.gnu.org https://hydra.gnu.org} is used
  858. (@code{mirror.hydra.gnu.org} is a mirror of @code{hydra.gnu.org}).
  859. This means that substitutes may be downloaded from @var{urls}, as long
  860. as they are signed by a trusted signature (@pxref{Substitutes}).
  861. @cindex build hook
  862. @item --no-build-hook
  863. Do not use the @dfn{build hook}.
  864. The build hook is a helper program that the daemon can start and to
  865. which it submits build requests. This mechanism is used to offload
  866. builds to other machines (@pxref{Daemon Offload Setup}).
  867. @item --cache-failures
  868. Cache build failures. By default, only successful builds are cached.
  869. When this option is used, @command{guix gc --list-failures} can be used
  870. to query the set of store items marked as failed; @command{guix gc
  871. --clear-failures} removes store items from the set of cached failures.
  872. @xref{Invoking guix gc}.
  873. @item --cores=@var{n}
  874. @itemx -c @var{n}
  875. Use @var{n} CPU cores to build each derivation; @code{0} means as many
  876. as available.
  877. The default value is @code{0}, but it may be overridden by clients, such
  878. as the @code{--cores} option of @command{guix build} (@pxref{Invoking
  879. guix build}).
  880. The effect is to define the @code{NIX_BUILD_CORES} environment variable
  881. in the build process, which can then use it to exploit internal
  882. parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
  883. @item --max-jobs=@var{n}
  884. @itemx -M @var{n}
  885. Allow at most @var{n} build jobs in parallel. The default value is
  886. @code{1}. Setting it to @code{0} means that no builds will be performed
  887. locally; instead, the daemon will offload builds (@pxref{Daemon Offload
  888. Setup}), or simply fail.
  889. @item --rounds=@var{N}
  890. Build each derivation @var{n} times in a row, and raise an error if
  891. consecutive build results are not bit-for-bit identical. Note that this
  892. setting can be overridden by clients such as @command{guix build}
  893. (@pxref{Invoking guix build}).
  894. When used in conjunction with @option{--keep-failed}, the differing
  895. output is kept in the store, under @file{/gnu/store/@dots{}-check}.
  896. This makes it easy to look for differences between the two results.
  897. @item --debug
  898. Produce debugging output.
  899. This is useful to debug daemon start-up issues, but then it may be
  900. overridden by clients, for example the @code{--verbosity} option of
  901. @command{guix build} (@pxref{Invoking guix build}).
  902. @item --chroot-directory=@var{dir}
  903. Add @var{dir} to the build chroot.
  904. Doing this may change the result of build processes---for instance if
  905. they use optional dependencies found in @var{dir} when it is available,
  906. and not otherwise. For that reason, it is not recommended to do so.
  907. Instead, make sure that each derivation declares all the inputs that it
  908. needs.
  909. @item --disable-chroot
  910. Disable chroot builds.
  911. Using this option is not recommended since, again, it would allow build
  912. processes to gain access to undeclared dependencies. It is necessary,
  913. though, when @command{guix-daemon} is running under an unprivileged user
  914. account.
  915. @item --disable-log-compression
  916. Disable compression of the build logs.
  917. Unless @code{--lose-logs} is used, all the build logs are kept in the
  918. @var{localstatedir}. To save space, the daemon automatically compresses
  919. them with bzip2 by default. This option disables that.
  920. @item --disable-deduplication
  921. @cindex deduplication
  922. Disable automatic file ``deduplication'' in the store.
  923. By default, files added to the store are automatically ``deduplicated'':
  924. if a newly added file is identical to another one found in the store,
  925. the daemon makes the new file a hard link to the other file. This can
  926. noticeably reduce disk usage, at the expense of slightly increased
  927. input/output load at the end of a build process. This option disables
  928. this optimization.
  929. @item --gc-keep-outputs[=yes|no]
  930. Tell whether the garbage collector (GC) must keep outputs of live
  931. derivations.
  932. When set to ``yes'', the GC will keep the outputs of any live derivation
  933. available in the store---the @code{.drv} files. The default is ``no'',
  934. meaning that derivation outputs are kept only if they are GC roots.
  935. @item --gc-keep-derivations[=yes|no]
  936. Tell whether the garbage collector (GC) must keep derivations
  937. corresponding to live outputs.
  938. When set to ``yes'', as is the case by default, the GC keeps
  939. derivations---i.e., @code{.drv} files---as long as at least one of their
  940. outputs is live. This allows users to keep track of the origins of
  941. items in their store. Setting it to ``no'' saves a bit of disk space.
  942. Note that when both @code{--gc-keep-derivations} and
  943. @code{--gc-keep-outputs} are used, the effect is to keep all the build
  944. prerequisites (the sources, compiler, libraries, and other build-time
  945. tools) of live objects in the store, regardless of whether these
  946. prerequisites are live. This is convenient for developers since it
  947. saves rebuilds or downloads.
  948. @item --impersonate-linux-2.6
  949. On Linux-based systems, impersonate Linux 2.6. This means that the
  950. kernel's @code{uname} system call will report 2.6 as the release number.
  951. This might be helpful to build programs that (usually wrongfully) depend
  952. on the kernel version number.
  953. @item --lose-logs
  954. Do not keep build logs. By default they are kept under
  955. @code{@var{localstatedir}/guix/log}.
  956. @item --system=@var{system}
  957. Assume @var{system} as the current system type. By default it is the
  958. architecture/kernel pair found at configure time, such as
  959. @code{x86_64-linux}.
  960. @item --listen=@var{socket}
  961. Listen for connections on @var{socket}, the file name of a Unix-domain
  962. socket. The default socket is
  963. @file{@var{localstatedir}/daemon-socket/socket}. This option is only
  964. useful in exceptional circumstances, such as if you need to run several
  965. daemons on the same machine.
  966. @end table
  967. @node Application Setup
  968. @section Application Setup
  969. @cindex foreign distro
  970. When using Guix on top of GNU/Linux distribution other than GuixSD---a
  971. so-called @dfn{foreign distro}---a few additional steps are needed to
  972. get everything in place. Here are some of them.
  973. @subsection Locales
  974. @anchor{locales-and-locpath}
  975. @cindex locales, when not on GuixSD
  976. @vindex LOCPATH
  977. @vindex GUIX_LOCPATH
  978. Packages installed @i{via} Guix will not use the locale data of the
  979. host system. Instead, you must first install one of the locale packages
  980. available with Guix and then define the @code{GUIX_LOCPATH} environment
  981. variable:
  982. @example
  983. $ guix package -i glibc-locales
  984. $ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale
  985. @end example
  986. Note that the @code{glibc-locales} package contains data for all the
  987. locales supported by the GNU@tie{}libc and weighs in at around
  988. 110@tie{}MiB. Alternatively, the @code{glibc-utf8-locales} is smaller but
  989. limited to a few UTF-8 locales.
  990. The @code{GUIX_LOCPATH} variable plays a role similar to @code{LOCPATH}
  991. (@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library Reference
  992. Manual}). There are two important differences though:
  993. @enumerate
  994. @item
  995. @code{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc
  996. provided by foreign distros. Thus, using @code{GUIX_LOCPATH} allows you
  997. to make sure the programs of the foreign distro will not end up loading
  998. incompatible locale data.
  999. @item
  1000. libc suffixes each entry of @code{GUIX_LOCPATH} with @code{/X.Y}, where
  1001. @code{X.Y} is the libc version---e.g., @code{2.22}. This means that,
  1002. should your Guix profile contain a mixture of programs linked against
  1003. different libc version, each libc version will only try to load locale
  1004. data in the right format.
  1005. @end enumerate
  1006. This is important because the locale data format used by different libc
  1007. versions may be incompatible.
  1008. @subsection Name Service Switch
  1009. @cindex name service switch, glibc
  1010. @cindex NSS (name service switch), glibc
  1011. @cindex nscd (name service caching daemon)
  1012. @cindex name service caching daemon (nscd)
  1013. When using Guix on a foreign distro, we @emph{strongly recommend} that
  1014. the system run the GNU C library's @dfn{name service cache daemon},
  1015. @command{nscd}, which should be listening on the
  1016. @file{/var/run/nscd/socket} socket. Failing to do that, applications
  1017. installed with Guix may fail to look up host names or user accounts, or
  1018. may even crash. The next paragraphs explain why.
  1019. @cindex @file{nsswitch.conf}
  1020. The GNU C library implements a @dfn{name service switch} (NSS), which is
  1021. an extensible mechanism for ``name lookups'' in general: host name
  1022. resolution, user accounts, and more (@pxref{Name Service Switch,,, libc,
  1023. The GNU C Library Reference Manual}).
  1024. @cindex Network information service (NIS)
  1025. @cindex NIS (Network information service)
  1026. Being extensible, the NSS supports @dfn{plugins}, which provide new name
  1027. lookup implementations: for example, the @code{nss-mdns} plugin allow
  1028. resolution of @code{.local} host names, the @code{nis} plugin allows
  1029. user account lookup using the Network information service (NIS), and so
  1030. on. These extra ``lookup services'' are configured system-wide in
  1031. @file{/etc/nsswitch.conf}, and all the programs running on the system
  1032. honor those settings (@pxref{NSS Configuration File,,, libc, The GNU C
  1033. Reference Manual}).
  1034. When they perform a name lookup---for instance by calling the
  1035. @code{getaddrinfo} function in C---applications first try to connect to
  1036. the nscd; on success, nscd performs name lookups on their behalf. If
  1037. the nscd is not running, then they perform the name lookup by
  1038. themselves, by loading the name lookup services into their own address
  1039. space and running it. These name lookup services---the
  1040. @file{libnss_*.so} files---are @code{dlopen}'d, but they may come from
  1041. the host system's C library, rather than from the C library the
  1042. application is linked against (the C library coming from Guix).
  1043. And this is where the problem is: if your application is linked against
  1044. Guix's C library (say, glibc 2.24) and tries to load NSS plugins from
  1045. another C library (say, @code{libnss_mdns.so} for glibc 2.22), it will
  1046. likely crash or have its name lookups fail unexpectedly.
  1047. Running @command{nscd} on the system, among other advantages, eliminates
  1048. this binary incompatibility problem because those @code{libnss_*.so}
  1049. files are loaded in the @command{nscd} process, not in applications
  1050. themselves.
  1051. @subsection X11 Fonts
  1052. @cindex fonts
  1053. The majority of graphical applications use Fontconfig to locate and
  1054. load fonts and perform X11-client-side rendering. The @code{fontconfig}
  1055. package in Guix looks for fonts in @file{$HOME/.guix-profile}
  1056. by default. Thus, to allow graphical applications installed with Guix
  1057. to display fonts, you have to install fonts with Guix as well.
  1058. Essential font packages include @code{gs-fonts}, @code{font-dejavu}, and
  1059. @code{font-gnu-freefont-ttf}.
  1060. To display text written in Chinese languages, Japanese, or Korean in
  1061. graphical applications, consider installing
  1062. @code{font-adobe-source-han-sans} or @code{font-wqy-zenhei}. The former
  1063. has multiple outputs, one per language family (@pxref{Packages with
  1064. Multiple Outputs}). For instance, the following command installs fonts
  1065. for Chinese languages:
  1066. @example
  1067. guix package -i font-adobe-source-han-sans:cn
  1068. @end example
  1069. @cindex @code{xterm}
  1070. Older programs such as @command{xterm} do not use Fontconfig and instead
  1071. rely on server-side font rendering. Such programs require to specify a
  1072. full name of a font using XLFD (X Logical Font Description), like this:
  1073. @example
  1074. -*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1
  1075. @end example
  1076. To be able to use such full names for the TrueType fonts installed in
  1077. your Guix profile, you need to extend the font path of the X server:
  1078. @example
  1079. xset +fp ~/.guix-profile/share/fonts/truetype
  1080. @end example
  1081. @cindex @code{xlsfonts}
  1082. After that, you can run @code{xlsfonts} (from @code{xlsfonts} package)
  1083. to make sure your TrueType fonts are listed there.
  1084. @subsection X.509 Certificates
  1085. @cindex @code{nss-certs}
  1086. The @code{nss-certs} package provides X.509 certificates, which allow
  1087. programs to authenticate Web servers accessed over HTTPS.
  1088. When using Guix on a foreign distro, you can install this package and
  1089. define the relevant environment variables so that packages know where to
  1090. look for certificates. @xref{X.509 Certificates}, for detailed
  1091. information.
  1092. @subsection Emacs Packages
  1093. @cindex @code{emacs}
  1094. When you install Emacs packages with Guix, the elisp files may be placed
  1095. either in @file{$HOME/.guix-profile/share/emacs/site-lisp/} or in
  1096. sub-directories of
  1097. @file{$HOME/.guix-profile/share/emacs/site-lisp/guix.d/}. The latter
  1098. directory exists because potentially there may exist thousands of Emacs
  1099. packages and storing all their files in a single directory may be not
  1100. reliable (because of name conflicts). So we think using a separate
  1101. directory for each package is a good idea. It is very similar to how
  1102. the Emacs package system organizes the file structure (@pxref{Package
  1103. Files,,, emacs, The GNU Emacs Manual}).
  1104. By default, Emacs (installed with Guix) ``knows'' where these packages
  1105. are placed, so you do not need to perform any configuration. If, for
  1106. some reason, you want to avoid auto-loading Emacs packages installed
  1107. with Guix, you can do so by running Emacs with @code{--no-site-file}
  1108. option (@pxref{Init File,,, emacs, The GNU Emacs Manual}).
  1109. @c TODO What else?
  1110. @c *********************************************************************
  1111. @node Package Management
  1112. @chapter Package Management
  1113. @cindex packages
  1114. The purpose of GNU Guix is to allow users to easily install, upgrade, and
  1115. remove software packages, without having to know about their build
  1116. procedures or dependencies. Guix also goes beyond this obvious set of
  1117. features.
  1118. This chapter describes the main features of Guix, as well as the package
  1119. management tools it provides. Along with the command-line interface
  1120. described below (@pxref{Invoking guix package, @code{guix package}}),
  1121. you may also use Emacs Interface, after installing @code{emacs-guix}
  1122. package (run @kbd{M-x guix-help} command to start with it):
  1123. @example
  1124. guix package -i emacs-guix
  1125. @end example
  1126. @menu
  1127. * Features:: How Guix will make your life brighter.
  1128. * Invoking guix package:: Package installation, removal, etc.
  1129. * Substitutes:: Downloading pre-built binaries.
  1130. * Packages with Multiple Outputs:: Single source package, multiple outputs.
  1131. * Invoking guix gc:: Running the garbage collector.
  1132. * Invoking guix pull:: Fetching the latest Guix and distribution.
  1133. * Invoking guix archive:: Exporting and importing store files.
  1134. @end menu
  1135. @node Features
  1136. @section Features
  1137. When using Guix, each package ends up in the @dfn{package store}, in its
  1138. own directory---something that resembles
  1139. @file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
  1140. Instead of referring to these directories, users have their own
  1141. @dfn{profile}, which points to the packages that they actually want to
  1142. use. These profiles are stored within each user's home directory, at
  1143. @code{$HOME/.guix-profile}.
  1144. For example, @code{alice} installs GCC 4.7.2. As a result,
  1145. @file{/home/alice/.guix-profile/bin/gcc} points to
  1146. @file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
  1147. @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
  1148. simply continues to point to
  1149. @file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
  1150. coexist on the same system without any interference.
  1151. The @command{guix package} command is the central tool to manage
  1152. packages (@pxref{Invoking guix package}). It operates on the per-user
  1153. profiles, and can be used @emph{with normal user privileges}.
  1154. @cindex transactions
  1155. The command provides the obvious install, remove, and upgrade
  1156. operations. Each invocation is actually a @emph{transaction}: either
  1157. the specified operation succeeds, or nothing happens. Thus, if the
  1158. @command{guix package} process is terminated during the transaction,
  1159. or if a power outage occurs during the transaction, then the user's
  1160. profile remains in its previous state, and remains usable.
  1161. In addition, any package transaction may be @emph{rolled back}. So, if,
  1162. for example, an upgrade installs a new version of a package that turns
  1163. out to have a serious bug, users may roll back to the previous instance
  1164. of their profile, which was known to work well. Similarly, the global
  1165. system configuration on GuixSD is subject to
  1166. transactional upgrades and roll-back
  1167. (@pxref{Using the Configuration System}).
  1168. All packages in the package store may be @emph{garbage-collected}.
  1169. Guix can determine which packages are still referenced by user
  1170. profiles, and remove those that are provably no longer referenced
  1171. (@pxref{Invoking guix gc}). Users may also explicitly remove old
  1172. generations of their profile so that the packages they refer to can be
  1173. collected.
  1174. @cindex reproducibility
  1175. @cindex reproducible builds
  1176. Finally, Guix takes a @dfn{purely functional} approach to package
  1177. management, as described in the introduction (@pxref{Introduction}).
  1178. Each @file{/gnu/store} package directory name contains a hash of all the
  1179. inputs that were used to build that package---compiler, libraries, build
  1180. scripts, etc. This direct correspondence allows users to make sure a
  1181. given package installation matches the current state of their
  1182. distribution. It also helps maximize @dfn{build reproducibility}:
  1183. thanks to the isolated build environments that are used, a given build
  1184. is likely to yield bit-identical files when performed on different
  1185. machines (@pxref{Invoking guix-daemon, container}).
  1186. @cindex substitutes
  1187. This foundation allows Guix to support @dfn{transparent binary/source
  1188. deployment}. When a pre-built binary for a @file{/gnu/store} item is
  1189. available from an external source---a @dfn{substitute}, Guix just
  1190. downloads it and unpacks it;
  1191. otherwise, it builds the package from source, locally
  1192. (@pxref{Substitutes}). Because build results are usually bit-for-bit
  1193. reproducible, users do not have to trust servers that provide
  1194. substitutes: they can force a local build and @emph{challenge} providers
  1195. (@pxref{Invoking guix challenge}).
  1196. Control over the build environment is a feature that is also useful for
  1197. developers. The @command{guix environment} command allows developers of
  1198. a package to quickly set up the right development environment for their
  1199. package, without having to manually install the dependencies of the
  1200. package into their profile (@pxref{Invoking guix environment}).
  1201. @node Invoking guix package
  1202. @section Invoking @command{guix package}
  1203. @cindex installing packages
  1204. @cindex removing packages
  1205. @cindex package installation
  1206. @cindex package removal
  1207. The @command{guix package} command is the tool that allows users to
  1208. install, upgrade, and remove packages, as well as rolling back to
  1209. previous configurations. It operates only on the user's own profile,
  1210. and works with normal user privileges (@pxref{Features}). Its syntax
  1211. is:
  1212. @example
  1213. guix package @var{options}
  1214. @end example
  1215. @cindex transactions
  1216. Primarily, @var{options} specifies the operations to be performed during
  1217. the transaction. Upon completion, a new profile is created, but
  1218. previous @dfn{generations} of the profile remain available, should the user
  1219. want to roll back.
  1220. For example, to remove @code{lua} and install @code{guile} and
  1221. @code{guile-cairo} in a single transaction:
  1222. @example
  1223. guix package -r lua -i guile guile-cairo
  1224. @end example
  1225. @command{guix package} also supports a @dfn{declarative approach}
  1226. whereby the user specifies the exact set of packages to be available and
  1227. passes it @i{via} the @option{--manifest} option
  1228. (@pxref{profile-manifest, @option{--manifest}}).
  1229. @cindex profile
  1230. For each user, a symlink to the user's default profile is automatically
  1231. created in @file{$HOME/.guix-profile}. This symlink always points to the
  1232. current generation of the user's default profile. Thus, users can add
  1233. @file{$HOME/.guix-profile/bin} to their @code{PATH} environment
  1234. variable, and so on.
  1235. @cindex search paths
  1236. If you are not using the Guix System Distribution, consider adding the
  1237. following lines to your @file{~/.bash_profile} (@pxref{Bash Startup
  1238. Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned
  1239. shells get all the right environment variable definitions:
  1240. @example
  1241. GUIX_PROFILE="$HOME/.guix-profile" \
  1242. source "$HOME/.guix-profile/etc/profile"
  1243. @end example
  1244. In a multi-user setup, user profiles are stored in a place registered as
  1245. a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
  1246. to (@pxref{Invoking guix gc}). That directory is normally
  1247. @code{@var{localstatedir}/profiles/per-user/@var{user}}, where
  1248. @var{localstatedir} is the value passed to @code{configure} as
  1249. @code{--localstatedir}, and @var{user} is the user name. The
  1250. @file{per-user} directory is created when @command{guix-daemon} is
  1251. started, and the @var{user} sub-directory is created by @command{guix
  1252. package}.
  1253. The @var{options} can be among the following:
  1254. @table @code
  1255. @item --install=@var{package} @dots{}
  1256. @itemx -i @var{package} @dots{}
  1257. Install the specified @var{package}s.
  1258. Each @var{package} may specify either a simple package name, such as
  1259. @code{guile}, or a package name followed by an at-sign and version number,
  1260. such as @code{guile@@1.8.8} or simply @code{guile@@1.8} (in the latter
  1261. case, the newest version prefixed by @code{1.8} is selected.)
  1262. If no version number is specified, the
  1263. newest available version will be selected. In addition, @var{package}
  1264. may contain a colon, followed by the name of one of the outputs of the
  1265. package, as in @code{gcc:doc} or @code{binutils@@2.22:lib}
  1266. (@pxref{Packages with Multiple Outputs}). Packages with a corresponding
  1267. name (and optionally version) are searched for among the GNU
  1268. distribution modules (@pxref{Package Modules}).
  1269. @cindex propagated inputs
  1270. Sometimes packages have @dfn{propagated inputs}: these are dependencies
  1271. that automatically get installed along with the required package
  1272. (@pxref{package-propagated-inputs, @code{propagated-inputs} in
  1273. @code{package} objects}, for information about propagated inputs in
  1274. package definitions).
  1275. @anchor{package-cmd-propagated-inputs}
  1276. An example is the GNU MPC library: its C header files refer to those of
  1277. the GNU MPFR library, which in turn refer to those of the GMP library.
  1278. Thus, when installing MPC, the MPFR and GMP libraries also get installed
  1279. in the profile; removing MPC also removes MPFR and GMP---unless they had
  1280. also been explicitly installed by the user.
  1281. Besides, packages sometimes rely on the definition of environment
  1282. variables for their search paths (see explanation of
  1283. @code{--search-paths} below). Any missing or possibly incorrect
  1284. environment variable definitions are reported here.
  1285. @item --install-from-expression=@var{exp}
  1286. @itemx -e @var{exp}
  1287. Install the package @var{exp} evaluates to.
  1288. @var{exp} must be a Scheme expression that evaluates to a
  1289. @code{<package>} object. This option is notably useful to disambiguate
  1290. between same-named variants of a package, with expressions such as
  1291. @code{(@@ (gnu packages base) guile-final)}.
  1292. Note that this option installs the first output of the specified
  1293. package, which may be insufficient when needing a specific output of a
  1294. multiple-output package.
  1295. @item --install-from-file=@var{file}
  1296. @itemx -f @var{file}
  1297. Install the package that the code within @var{file} evaluates to.
  1298. As an example, @var{file} might contain a definition like this
  1299. (@pxref{Defining Packages}):
  1300. @example
  1301. @verbatiminclude package-hello.scm
  1302. @end example
  1303. Developers may find it useful to include such a @file{guix.scm} file
  1304. in the root of their project source tree that can be used to test
  1305. development snapshots and create reproducible development environments
  1306. (@pxref{Invoking guix environment}).
  1307. @item --remove=@var{package} @dots{}
  1308. @itemx -r @var{package} @dots{}
  1309. Remove the specified @var{package}s.
  1310. As for @code{--install}, each @var{package} may specify a version number
  1311. and/or output name in addition to the package name. For instance,
  1312. @code{-r glibc:debug} would remove the @code{debug} output of
  1313. @code{glibc}.
  1314. @item --upgrade[=@var{regexp} @dots{}]
  1315. @itemx -u [@var{regexp} @dots{}]
  1316. @cindex upgrading packages
  1317. Upgrade all the installed packages. If one or more @var{regexp}s are
  1318. specified, upgrade only installed packages whose name matches a
  1319. @var{regexp}. Also see the @code{--do-not-upgrade} option below.
  1320. Note that this upgrades package to the latest version of packages found
  1321. in the distribution currently installed. To update your distribution,
  1322. you should regularly run @command{guix pull} (@pxref{Invoking guix
  1323. pull}).
  1324. @item --do-not-upgrade[=@var{regexp} @dots{}]
  1325. When used together with the @code{--upgrade} option, do @emph{not}
  1326. upgrade any packages whose name matches a @var{regexp}. For example, to
  1327. upgrade all packages in the current profile except those containing the
  1328. substring ``emacs'':
  1329. @example
  1330. $ guix package --upgrade . --do-not-upgrade emacs
  1331. @end example
  1332. @item @anchor{profile-manifest}--manifest=@var{file}
  1333. @itemx -m @var{file}
  1334. @cindex profile declaration
  1335. @cindex profile manifest
  1336. Create a new generation of the profile from the manifest object
  1337. returned by the Scheme code in @var{file}.
  1338. This allows you to @emph{declare} the profile's contents rather than
  1339. constructing it through a sequence of @code{--install} and similar
  1340. commands. The advantage is that @var{file} can be put under version
  1341. control, copied to different machines to reproduce the same profile, and
  1342. so on.
  1343. @c FIXME: Add reference to (guix profile) documentation when available.
  1344. @var{file} must return a @dfn{manifest} object, which is roughly a list
  1345. of packages:
  1346. @findex packages->manifest
  1347. @example
  1348. (use-package-modules guile emacs)
  1349. (packages->manifest
  1350. (list emacs
  1351. guile-2.0
  1352. ;; Use a specific package output.
  1353. (list guile-2.0 "debug")))
  1354. @end example
  1355. @item --roll-back
  1356. @cindex rolling back
  1357. @cindex undoing transactions
  1358. @cindex transactions, undoing
  1359. Roll back to the previous @dfn{generation} of the profile---i.e., undo
  1360. the last transaction.
  1361. When combined with options such as @code{--install}, roll back occurs
  1362. before any other actions.
  1363. When rolling back from the first generation that actually contains
  1364. installed packages, the profile is made to point to the @dfn{zeroth
  1365. generation}, which contains no files apart from its own metadata.
  1366. After having rolled back, installing, removing, or upgrading packages
  1367. overwrites previous future generations. Thus, the history of the
  1368. generations in a profile is always linear.
  1369. @item --switch-generation=@var{pattern}
  1370. @itemx -S @var{pattern}
  1371. @cindex generations
  1372. Switch to a particular generation defined by @var{pattern}.
  1373. @var{pattern} may be either a generation number or a number prefixed
  1374. with ``+'' or ``-''. The latter means: move forward/backward by a
  1375. specified number of generations. For example, if you want to return to
  1376. the latest generation after @code{--roll-back}, use
  1377. @code{--switch-generation=+1}.
  1378. The difference between @code{--roll-back} and
  1379. @code{--switch-generation=-1} is that @code{--switch-generation} will
  1380. not make a zeroth generation, so if a specified generation does not
  1381. exist, the current generation will not be changed.
  1382. @item --search-paths[=@var{kind}]
  1383. @cindex search paths
  1384. Report environment variable definitions, in Bash syntax, that may be
  1385. needed in order to use the set of installed packages. These environment
  1386. variables are used to specify @dfn{search paths} for files used by some
  1387. of the installed packages.
  1388. For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
  1389. environment variables to be defined so it can look for headers and
  1390. libraries in the user's profile (@pxref{Environment Variables,,, gcc,
  1391. Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
  1392. library are installed in the profile, then @code{--search-paths} will
  1393. suggest setting these variables to @code{@var{profile}/include} and
  1394. @code{@var{profile}/lib}, respectively.
  1395. The typical use case is to define these environment variables in the
  1396. shell:
  1397. @example
  1398. $ eval `guix package --search-paths`
  1399. @end example
  1400. @var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix},
  1401. meaning that the returned environment variable definitions will either
  1402. be exact settings, or prefixes or suffixes of the current value of these
  1403. variables. When omitted, @var{kind} defaults to @code{exact}.
  1404. This option can also be used to compute the @emph{combined} search paths
  1405. of several profiles. Consider this example:
  1406. @example
  1407. $ guix package -p foo -i guile
  1408. $ guix package -p bar -i guile-json
  1409. $ guix package -p foo -p bar --search-paths
  1410. @end example
  1411. The last command above reports about the @code{GUILE_LOAD_PATH}
  1412. variable, even though, taken individually, neither @file{foo} nor
  1413. @file{bar} would lead to that recommendation.
  1414. @item --profile=@var{profile}
  1415. @itemx -p @var{profile}
  1416. Use @var{profile} instead of the user's default profile.
  1417. @item --verbose
  1418. Produce verbose output. In particular, emit the build log of the
  1419. environment on the standard error port.
  1420. @item --bootstrap
  1421. Use the bootstrap Guile to build the profile. This option is only
  1422. useful to distribution developers.
  1423. @end table
  1424. In addition to these actions, @command{guix package} supports the
  1425. following options to query the current state of a profile, or the
  1426. availability of packages:
  1427. @table @option
  1428. @item --search=@var{regexp}
  1429. @itemx -s @var{regexp}
  1430. @cindex searching for packages
  1431. List the available packages whose name, synopsis, or description matches
  1432. @var{regexp}. Print all the metadata of matching packages in
  1433. @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
  1434. GNU recutils manual}).
  1435. This allows specific fields to be extracted using the @command{recsel}
  1436. command, for instance:
  1437. @example
  1438. $ guix package -s malloc | recsel -p name,version
  1439. name: glibc
  1440. version: 2.17
  1441. name: libgc
  1442. version: 7.2alpha6
  1443. @end example
  1444. Similarly, to show the name of all the packages available under the
  1445. terms of the GNU@tie{}LGPL version 3:
  1446. @example
  1447. $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
  1448. name: elfutils
  1449. name: gmp
  1450. @dots{}
  1451. @end example
  1452. It is also possible to refine search results using several @code{-s}
  1453. flags. For example, the following command returns a list of board
  1454. games:
  1455. @example
  1456. $ guix package -s '\<board\>' -s game | recsel -p name
  1457. name: gnubg
  1458. @dots{}
  1459. @end example
  1460. If we were to omit @code{-s game}, we would also get software packages
  1461. that deal with printed circuit boards; removing the angle brackets
  1462. around @code{board} would further add packages that have to do with
  1463. keyboards.
  1464. And now for a more elaborate example. The following command searches
  1465. for cryptographic libraries, filters out Haskell, Perl, Python, and Ruby
  1466. libraries, and prints the name and synopsis of the matching packages:
  1467. @example
  1468. $ guix package -s crypto -s library | \
  1469. recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
  1470. @end example
  1471. @noindent
  1472. @xref{Selection Expressions,,, recutils, GNU recutils manual}, for more
  1473. information on @dfn{selection expressions} for @code{recsel -e}.
  1474. @item --show=@var{package}
  1475. Show details about @var{package}, taken from the list of available packages, in
  1476. @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
  1477. recutils manual}).
  1478. @example
  1479. $ guix package --show=python | recsel -p name,version
  1480. name: python
  1481. version: 2.7.6
  1482. name: python
  1483. version: 3.3.5
  1484. @end example
  1485. You may also specify the full name of a package to only get details about a
  1486. specific version of it:
  1487. @example
  1488. $ guix package --show=python@@3.4 | recsel -p name,version
  1489. name: python
  1490. version: 3.4.3
  1491. @end example
  1492. @item --list-installed[=@var{regexp}]
  1493. @itemx -I [@var{regexp}]
  1494. List the currently installed packages in the specified profile, with the
  1495. most recently installed packages shown last. When @var{regexp} is
  1496. specified, list only installed packages whose name matches @var{regexp}.
  1497. For each installed package, print the following items, separated by
  1498. tabs: the package name, its version string, the part of the package that
  1499. is installed (for instance, @code{out} for the default output,
  1500. @code{include} for its headers, etc.), and the path of this package in
  1501. the store.
  1502. @item --list-available[=@var{regexp}]
  1503. @itemx -A [@var{regexp}]
  1504. List packages currently available in the distribution for this system
  1505. (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
  1506. installed packages whose name matches @var{regexp}.
  1507. For each package, print the following items separated by tabs: its name,
  1508. its version string, the parts of the package (@pxref{Packages with
  1509. Multiple Outputs}), and the source location of its definition.
  1510. @item --list-generations[=@var{pattern}]
  1511. @itemx -l [@var{pattern}]
  1512. @cindex generations
  1513. Return a list of generations along with their creation dates; for each
  1514. generation, show the installed packages, with the most recently
  1515. installed packages shown last. Note that the zeroth generation is never
  1516. shown.
  1517. For each installed package, print the following items, separated by
  1518. tabs: the name of a package, its version string, the part of the package
  1519. that is installed (@pxref{Packages with Multiple Outputs}), and the
  1520. location of this package in the store.
  1521. When @var{pattern} is used, the command returns only matching
  1522. generations. Valid patterns include:
  1523. @itemize
  1524. @item @emph{Integers and comma-separated integers}. Both patterns denote
  1525. generation numbers. For instance, @code{--list-generations=1} returns
  1526. the first one.
  1527. And @code{--list-generations=1,8,2} outputs three generations in the
  1528. specified order. Neither spaces nor trailing commas are allowed.
  1529. @item @emph{Ranges}. @code{--list-generations=2..9} prints the
  1530. specified generations and everything in between. Note that the start of
  1531. a range must be smaller than its end.
  1532. It is also possible to omit the endpoint. For example,
  1533. @code{--list-generations=2..}, returns all generations starting from the
  1534. second one.
  1535. @item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
  1536. or months by passing an integer along with the first letter of the
  1537. duration. For example, @code{--list-generations=20d} lists generations
  1538. that are up to 20 days old.
  1539. @end itemize
  1540. @item --delete-generations[=@var{pattern}]
  1541. @itemx -d [@var{pattern}]
  1542. When @var{pattern} is omitted, delete all generations except the current
  1543. one.
  1544. This command accepts the same patterns as @option{--list-generations}.
  1545. When @var{pattern} is specified, delete the matching generations. When
  1546. @var{pattern} specifies a duration, generations @emph{older} than the
  1547. specified duration match. For instance, @code{--delete-generations=1m}
  1548. deletes generations that are more than one month old.
  1549. If the current generation matches, it is @emph{not} deleted. Also, the
  1550. zeroth generation is never deleted.
  1551. Note that deleting generations prevents rolling back to them.
  1552. Consequently, this command must be used with care.
  1553. @end table
  1554. Finally, since @command{guix package} may actually start build
  1555. processes, it supports all the common build options (@pxref{Common Build
  1556. Options}). It also supports package transformation options, such as
  1557. @option{--with-source} (@pxref{Package Transformation Options}).
  1558. However, note that package transformations are lost when upgrading; to
  1559. preserve transformations across upgrades, you should define your own
  1560. package variant in a Guile module and add it to @code{GUIX_PACKAGE_PATH}
  1561. (@pxref{Defining Packages}).
  1562. @node Substitutes
  1563. @section Substitutes
  1564. @cindex substitutes
  1565. @cindex pre-built binaries
  1566. Guix supports transparent source/binary deployment, which means that it
  1567. can either build things locally, or download pre-built items from a
  1568. server. We call these pre-built items @dfn{substitutes}---they are
  1569. substitutes for local build results. In many cases, downloading a
  1570. substitute is much faster than building things locally.
  1571. Substitutes can be anything resulting from a derivation build
  1572. (@pxref{Derivations}). Of course, in the common case, they are
  1573. pre-built package binaries, but source tarballs, for instance, which
  1574. also result from derivation builds, can be available as substitutes.
  1575. The @code{hydra.gnu.org} server is a front-end to a build farm that
  1576. builds packages from the GNU distribution continuously for some
  1577. architectures, and makes them available as substitutes. This is the
  1578. default source of substitutes; it can be overridden by passing the
  1579. @option{--substitute-urls} option either to @command{guix-daemon}
  1580. (@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
  1581. or to client tools such as @command{guix package}
  1582. (@pxref{client-substitute-urls,, client @option{--substitute-urls}
  1583. option}).
  1584. Substitute URLs can be either HTTP or HTTPS@footnote{For HTTPS access,
  1585. the Guile bindings of GnuTLS must be installed. @xref{Requirements}.}
  1586. HTTPS is recommended because communications are encrypted; conversely,
  1587. using HTTP makes all communications visible to an eavesdropper, who
  1588. could use the information gathered to determine, for instance, whether
  1589. your system has unpatched security vulnerabilities.
  1590. @cindex security
  1591. @cindex digital signatures
  1592. @cindex substitutes, authorization thereof
  1593. To allow Guix to download substitutes from @code{hydra.gnu.org} or a
  1594. mirror thereof, you
  1595. must add its public key to the access control list (ACL) of archive
  1596. imports, using the @command{guix archive} command (@pxref{Invoking guix
  1597. archive}). Doing so implies that you trust @code{hydra.gnu.org} to not
  1598. be compromised and to serve genuine substitutes.
  1599. This public key is installed along with Guix, in
  1600. @code{@var{prefix}/share/guix/hydra.gnu.org.pub}, where @var{prefix} is
  1601. the installation prefix of Guix. If you installed Guix from source,
  1602. make sure you checked the GPG signature of
  1603. @file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
  1604. Then, you can run something like this:
  1605. @example
  1606. # guix archive --authorize < hydra.gnu.org.pub
  1607. @end example
  1608. Once this is in place, the output of a command like @code{guix build}
  1609. should change from something like:
  1610. @example
  1611. $ guix build emacs --dry-run
  1612. The following derivations would be built:
  1613. /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
  1614. /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
  1615. /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
  1616. /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
  1617. @dots{}
  1618. @end example
  1619. @noindent
  1620. to something like:
  1621. @example
  1622. $ guix build emacs --dry-run
  1623. The following files would be downloaded:
  1624. /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
  1625. /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
  1626. /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
  1627. /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
  1628. @dots{}
  1629. @end example
  1630. @noindent
  1631. This indicates that substitutes from @code{hydra.gnu.org} are usable and
  1632. will be downloaded, when possible, for future builds.
  1633. Guix ignores substitutes that are not signed, or that are not signed by
  1634. one of the keys listed in the ACL. It also detects and raises an error
  1635. when attempting to use a substitute that has been tampered with.
  1636. @vindex http_proxy
  1637. Substitutes are downloaded over HTTP or HTTPS.
  1638. The @code{http_proxy} environment
  1639. variable can be set in the environment of @command{guix-daemon} and is
  1640. honored for downloads of substitutes. Note that the value of
  1641. @code{http_proxy} in the environment where @command{guix build},
  1642. @command{guix package}, and other client commands are run has
  1643. @emph{absolutely no effect}.
  1644. When using HTTPS, the server's X.509 certificate is @emph{not} validated
  1645. (in other words, the server is not authenticated), contrary to what
  1646. HTTPS clients such as Web browsers usually do. This is because Guix
  1647. authenticates substitute information itself, as explained above, which
  1648. is what we care about (whereas X.509 certificates are about
  1649. authenticating bindings between domain names and public keys.)
  1650. The substitute mechanism can be disabled globally by running
  1651. @code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
  1652. guix-daemon}). It can also be disabled temporarily by passing the
  1653. @code{--no-substitutes} option to @command{guix package}, @command{guix
  1654. build}, and other command-line tools.
  1655. @unnumberedsubsec On Trusting Binaries
  1656. Today, each individual's control over their own computing is at the
  1657. mercy of institutions, corporations, and groups with enough power and
  1658. determination to subvert the computing infrastructure and exploit its
  1659. weaknesses. While using @code{hydra.gnu.org} substitutes can be
  1660. convenient, we encourage users to also build on their own, or even run
  1661. their own build farm, such that @code{hydra.gnu.org} is less of an
  1662. interesting target. One way to help is by publishing the software you
  1663. build using @command{guix publish} so that others have one more choice
  1664. of server to download substitutes from (@pxref{Invoking guix publish}).
  1665. Guix has the foundations to maximize build reproducibility
  1666. (@pxref{Features}). In most cases, independent builds of a given
  1667. package or derivation should yield bit-identical results. Thus, through
  1668. a diverse set of independent package builds, we can strengthen the
  1669. integrity of our systems. The @command{guix challenge} command aims to
  1670. help users assess substitute servers, and to assist developers in
  1671. finding out about non-deterministic package builds (@pxref{Invoking guix
  1672. challenge}). Similarly, the @option{--check} option of @command{guix
  1673. build} allows users to check whether previously-installed substitutes
  1674. are genuine by rebuilding them locally (@pxref{build-check,
  1675. @command{guix build --check}}).
  1676. In the future, we want Guix to have support to publish and retrieve
  1677. binaries to/from other users, in a peer-to-peer fashion. If you would
  1678. like to discuss this project, join us on @email{guix-devel@@gnu.org}.
  1679. @node Packages with Multiple Outputs
  1680. @section Packages with Multiple Outputs
  1681. @cindex multiple-output packages
  1682. @cindex package outputs
  1683. @cindex outputs
  1684. Often, packages defined in Guix have a single @dfn{output}---i.e., the
  1685. source package leads to exactly one directory in the store. When running
  1686. @command{guix package -i glibc}, one installs the default output of the
  1687. GNU libc package; the default output is called @code{out}, but its name
  1688. can be omitted as shown in this command. In this particular case, the
  1689. default output of @code{glibc} contains all the C header files, shared
  1690. libraries, static libraries, Info documentation, and other supporting
  1691. files.
  1692. Sometimes it is more appropriate to separate the various types of files
  1693. produced from a single source package into separate outputs. For
  1694. instance, the GLib C library (used by GTK+ and related packages)
  1695. installs more than 20 MiB of reference documentation as HTML pages.
  1696. To save space for users who do not need it, the documentation goes to a
  1697. separate output, called @code{doc}. To install the main GLib output,
  1698. which contains everything but the documentation, one would run:
  1699. @example
  1700. guix package -i glib
  1701. @end example
  1702. @cindex documentation
  1703. The command to install its documentation is:
  1704. @example
  1705. guix package -i glib:doc
  1706. @end example
  1707. Some packages install programs with different ``dependency footprints''.
  1708. For instance, the WordNet package installs both command-line tools and
  1709. graphical user interfaces (GUIs). The former depend solely on the C
  1710. library, whereas the latter depend on Tcl/Tk and the underlying X
  1711. libraries. In this case, we leave the command-line tools in the default
  1712. output, whereas the GUIs are in a separate output. This allows users
  1713. who do not need the GUIs to save space. The @command{guix size} command
  1714. can help find out about such situations (@pxref{Invoking guix size}).
  1715. @command{guix graph} can also be helpful (@pxref{Invoking guix graph}).
  1716. There are several such multiple-output packages in the GNU distribution.
  1717. Other conventional output names include @code{lib} for libraries and
  1718. possibly header files, @code{bin} for stand-alone programs, and
  1719. @code{debug} for debugging information (@pxref{Installing Debugging
  1720. Files}). The outputs of a packages are listed in the third column of
  1721. the output of @command{guix package --list-available} (@pxref{Invoking
  1722. guix package}).
  1723. @node Invoking guix gc
  1724. @section Invoking @command{guix gc}
  1725. @cindex garbage collector
  1726. @cindex disk space
  1727. Packages that are installed, but not used, may be @dfn{garbage-collected}.
  1728. The @command{guix gc} command allows users to explicitly run the garbage
  1729. collector to reclaim space from the @file{/gnu/store} directory. It is
  1730. the @emph{only} way to remove files from @file{/gnu/store}---removing
  1731. files or directories manually may break it beyond repair!
  1732. The garbage collector has a set of known @dfn{roots}: any file under
  1733. @file{/gnu/store} reachable from a root is considered @dfn{live} and
  1734. cannot be deleted; any other file is considered @dfn{dead} and may be
  1735. deleted. The set of garbage collector roots includes default user
  1736. profiles, and may be augmented with @command{guix build --root}, for
  1737. example (@pxref{Invoking guix build}).
  1738. Prior to running @code{guix gc --collect-garbage} to make space, it is
  1739. often useful to remove old generations from user profiles; that way, old
  1740. package builds referenced by those generations can be reclaimed. This
  1741. is achieved by running @code{guix package --delete-generations}
  1742. (@pxref{Invoking guix package}).
  1743. The @command{guix gc} command has three modes of operation: it can be
  1744. used to garbage-collect any dead files (the default), to delete specific
  1745. files (the @code{--delete} option), to print garbage-collector
  1746. information, or for more advanced queries. The garbage collection
  1747. options are as follows:
  1748. @table @code
  1749. @item --collect-garbage[=@var{min}]
  1750. @itemx -C [@var{min}]
  1751. Collect garbage---i.e., unreachable @file{/gnu/store} files and
  1752. sub-directories. This is the default operation when no option is
  1753. specified.
  1754. When @var{min} is given, stop once @var{min} bytes have been collected.
  1755. @var{min} may be a number of bytes, or it may include a unit as a
  1756. suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
  1757. (@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
  1758. When @var{min} is omitted, collect all the garbage.
  1759. @item --free-space=@var{free}
  1760. @itemx -F @var{free}
  1761. Collect garbage until @var{free} space is available under
  1762. @file{/gnu/store}, if possible; @var{free} denotes storage space, such
  1763. as @code{500MiB}, as described above.
  1764. When @var{free} or more is already available in @file{/gnu/store}, do
  1765. nothing and exit immediately.
  1766. @item --delete
  1767. @itemx -d
  1768. Attempt to delete all the store files and directories specified as
  1769. arguments. This fails if some of the files are not in the store, or if
  1770. they are still live.
  1771. @item --list-failures
  1772. List store items corresponding to cached build failures.
  1773. This prints nothing unless the daemon was started with
  1774. @option{--cache-failures} (@pxref{Invoking guix-daemon,
  1775. @option{--cache-failures}}).
  1776. @item --clear-failures
  1777. Remove the specified store items from the failed-build cache.
  1778. Again, this option only makes sense when the daemon is started with
  1779. @option{--cache-failures}. Otherwise, it does nothing.
  1780. @item --list-dead
  1781. Show the list of dead files and directories still present in the
  1782. store---i.e., files and directories no longer reachable from any root.
  1783. @item --list-live
  1784. Show the list of live store files and directories.
  1785. @end table
  1786. In addition, the references among existing store files can be queried:
  1787. @table @code
  1788. @item --references
  1789. @itemx --referrers
  1790. @cindex package dependencies
  1791. List the references (respectively, the referrers) of store files given
  1792. as arguments.
  1793. @item --requisites
  1794. @itemx -R
  1795. @cindex closure
  1796. List the requisites of the store files passed as arguments. Requisites
  1797. include the store files themselves, their references, and the references
  1798. of these, recursively. In other words, the returned list is the
  1799. @dfn{transitive closure} of the store files.
  1800. @xref{Invoking guix size}, for a tool to profile the size of the closure
  1801. of an element. @xref{Invoking guix graph}, for a tool to visualize
  1802. the graph of references.
  1803. @end table
  1804. Lastly, the following options allow you to check the integrity of the
  1805. store and to control disk usage.
  1806. @table @option
  1807. @item --verify[=@var{options}]
  1808. @cindex integrity, of the store
  1809. @cindex integrity checking
  1810. Verify the integrity of the store.
  1811. By default, make sure that all the store items marked as valid in the
  1812. database of the daemon actually exist in @file{/gnu/store}.
  1813. When provided, @var{options} must be a comma-separated list containing one
  1814. or more of @code{contents} and @code{repair}.
  1815. When passing @option{--verify=contents}, the daemon computes the
  1816. content hash of each store item and compares it against its hash in the
  1817. database. Hash mismatches are reported as data corruptions. Because it
  1818. traverses @emph{all the files in the store}, this command can take a
  1819. long time, especially on systems with a slow disk drive.
  1820. @cindex repairing the store
  1821. Using @option{--verify=repair} or @option{--verify=contents,repair}
  1822. causes the daemon to try to repair corrupt store items by fetching
  1823. substitutes for them (@pxref{Substitutes}). Because repairing is not
  1824. atomic, and thus potentially dangerous, it is available only to the
  1825. system administrator.
  1826. @item --optimize
  1827. @cindex deduplication
  1828. Optimize the store by hard-linking identical files---this is
  1829. @dfn{deduplication}.
  1830. The daemon performs deduplication after each successful build or archive
  1831. import, unless it was started with @code{--disable-deduplication}
  1832. (@pxref{Invoking guix-daemon, @code{--disable-deduplication}}). Thus,
  1833. this option is primarily useful when the daemon was running with
  1834. @code{--disable-deduplication}.
  1835. @end table
  1836. @node Invoking guix pull
  1837. @section Invoking @command{guix pull}
  1838. @cindex upgrading Guix
  1839. @cindex updating Guix
  1840. @cindex @command{guix pull}
  1841. @cindex pull
  1842. Packages are installed or upgraded to the latest version available in
  1843. the distribution currently available on your local machine. To update
  1844. that distribution, along with the Guix tools, you must run @command{guix
  1845. pull}: the command downloads the latest Guix source code and package
  1846. descriptions, and deploys it.
  1847. On completion, @command{guix package} will use packages and package
  1848. versions from this just-retrieved copy of Guix. Not only that, but all
  1849. the Guix commands and Scheme modules will also be taken from that latest
  1850. version. New @command{guix} sub-commands added by the update also
  1851. become available.
  1852. Any user can update their Guix copy using @command{guix pull}, and the
  1853. effect is limited to the user who run @command{guix pull}. For
  1854. instance, when user @code{root} runs @command{guix pull}, this has no
  1855. effect on the version of Guix that user @code{alice} sees, and vice
  1856. versa@footnote{Under the hood, @command{guix pull} updates the
  1857. @file{~/.config/guix/latest} symbolic link to point to the latest Guix,
  1858. and the @command{guix} command loads code from there.}.
  1859. The @command{guix pull} command is usually invoked with no arguments,
  1860. but it supports the following options:
  1861. @table @code
  1862. @item --verbose
  1863. Produce verbose output, writing build logs to the standard error output.
  1864. @item --url=@var{url}
  1865. Download the source tarball of Guix from @var{url}.
  1866. By default, the tarball is taken from its canonical address at
  1867. @code{gnu.org}, for the stable branch of Guix.
  1868. @item --bootstrap
  1869. Use the bootstrap Guile to build the latest Guix. This option is only
  1870. useful to Guix developers.
  1871. @end table
  1872. @node Invoking guix archive
  1873. @section Invoking @command{guix archive}
  1874. @cindex @command{guix archive}
  1875. @cindex archive
  1876. The @command{guix archive} command allows users to @dfn{export} files
  1877. from the store into a single archive, and to later @dfn{import} them.
  1878. In particular, it allows store files to be transferred from one machine
  1879. to the store on another machine.
  1880. @cindex exporting store items
  1881. To export store files as an archive to standard output, run:
  1882. @example
  1883. guix archive --export @var{options} @var{specifications}...
  1884. @end example
  1885. @var{specifications} may be either store file names or package
  1886. specifications, as for @command{guix package} (@pxref{Invoking guix
  1887. package}). For instance, the following command creates an archive
  1888. containing the @code{gui} output of the @code{git} package and the main
  1889. output of @code{emacs}:
  1890. @example
  1891. guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
  1892. @end example
  1893. If the specified packages are not built yet, @command{guix archive}
  1894. automatically builds them. The build process may be controlled with the
  1895. common build options (@pxref{Common Build Options}).
  1896. To transfer the @code{emacs} package to a machine connected over SSH,
  1897. one would run:
  1898. @example
  1899. guix archive --export -r emacs | ssh the-machine guix archive --import
  1900. @end example
  1901. @noindent
  1902. Similarly, a complete user profile may be transferred from one machine
  1903. to another like this:
  1904. @example
  1905. guix archive --export -r $(readlink -f ~/.guix-profile) | \
  1906. ssh the-machine guix-archive --import
  1907. @end example
  1908. @noindent
  1909. However, note that, in both examples, all of @code{emacs} and the
  1910. profile as well as all of their dependencies are transferred (due to
  1911. @code{-r}), regardless of what is already available in the store on the
  1912. target machine. The @code{--missing} option can help figure out which
  1913. items are missing from the target store.
  1914. @cindex nar, archive format
  1915. @cindex normalized archive (nar)
  1916. Archives are stored in the ``normalized archive'' or ``nar'' format, which is
  1917. comparable in spirit to `tar', but with differences
  1918. that make it more appropriate for our purposes. First, rather than
  1919. recording all Unix metadata for each file, the nar format only mentions
  1920. the file type (regular, directory, or symbolic link); Unix permissions
  1921. and owner/group are dismissed. Second, the order in which directory
  1922. entries are stored always follows the order of file names according to
  1923. the C locale collation order. This makes archive production fully
  1924. deterministic.
  1925. When exporting, the daemon digitally signs the contents of the archive,
  1926. and that digital signature is appended. When importing, the daemon
  1927. verifies the signature and rejects the import in case of an invalid
  1928. signature or if the signing key is not authorized.
  1929. @c FIXME: Add xref to daemon doc about signatures.
  1930. The main options are:
  1931. @table @code
  1932. @item --export
  1933. Export the specified store files or packages (see below.) Write the
  1934. resulting archive to the standard output.
  1935. Dependencies are @emph{not} included in the output, unless
  1936. @code{--recursive} is passed.
  1937. @item -r
  1938. @itemx --recursive
  1939. When combined with @code{--export}, this instructs @command{guix
  1940. archive} to include dependencies of the given items in the archive.
  1941. Thus, the resulting archive is self-contained: it contains the closure
  1942. of the exported store items.
  1943. @item --import
  1944. Read an archive from the standard input, and import the files listed
  1945. therein into the store. Abort if the archive has an invalid digital
  1946. signature, or if it is signed by a public key not among the authorized
  1947. keys (see @code{--authorize} below.)
  1948. @item --missing
  1949. Read a list of store file names from the standard input, one per line,
  1950. and write on the standard output the subset of these files missing from
  1951. the store.
  1952. @item --generate-key[=@var{parameters}]
  1953. @cindex signing, archives
  1954. Generate a new key pair for the daemon. This is a prerequisite before
  1955. archives can be exported with @code{--export}. Note that this operation
  1956. usually takes time, because it needs to gather enough entropy to
  1957. generate the key pair.
  1958. The generated key pair is typically stored under @file{/etc/guix}, in
  1959. @file{signing-key.pub} (public key) and @file{signing-key.sec} (private
  1960. key, which must be kept secret.) When @var{parameters} is omitted,
  1961. an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
  1962. versions before 1.6.0, it is a 4096-bit RSA key.
  1963. Alternatively, @var{parameters} can specify
  1964. @code{genkey} parameters suitable for Libgcrypt (@pxref{General
  1965. public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
  1966. Libgcrypt Reference Manual}).
  1967. @item --authorize
  1968. @cindex authorizing, archives
  1969. Authorize imports signed by the public key passed on standard input.
  1970. The public key must be in ``s-expression advanced format''---i.e., the
  1971. same format as the @file{signing-key.pub} file.
  1972. The list of authorized keys is kept in the human-editable file
  1973. @file{/etc/guix/acl}. The file contains
  1974. @url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
  1975. s-expressions''} and is structured as an access-control list in the
  1976. @url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
  1977. (SPKI)}.
  1978. @item --extract=@var{directory}
  1979. @itemx -x @var{directory}
  1980. Read a single-item archive as served by substitute servers
  1981. (@pxref{Substitutes}) and extract it to @var{directory}. This is a
  1982. low-level operation needed in only very narrow use cases; see below.
  1983. For example, the following command extracts the substitute for Emacs
  1984. served by @code{hydra.gnu.org} to @file{/tmp/emacs}:
  1985. @example
  1986. $ wget -O - \
  1987. https://hydra.gnu.org/nar/@dots{}-emacs-24.5 \
  1988. | bunzip2 | guix archive -x /tmp/emacs
  1989. @end example
  1990. Single-item archives are different from multiple-item archives produced
  1991. by @command{guix archive --export}; they contain a single store item,
  1992. and they do @emph{not} embed a signature. Thus this operation does
  1993. @emph{no} signature verification and its output should be considered
  1994. unsafe.
  1995. The primary purpose of this operation is to facilitate inspection of
  1996. archive contents coming from possibly untrusted substitute servers.
  1997. @end table
  1998. @c *********************************************************************
  1999. @node Programming Interface
  2000. @chapter Programming Interface
  2001. GNU Guix provides several Scheme programming interfaces (APIs) to
  2002. define, build, and query packages. The first interface allows users to
  2003. write high-level package definitions. These definitions refer to
  2004. familiar packaging concepts, such as the name and version of a package,
  2005. its build system, and its dependencies. These definitions can then be
  2006. turned into concrete build actions.
  2007. Build actions are performed by the Guix daemon, on behalf of users. In a
  2008. standard setup, the daemon has write access to the store---the
  2009. @file{/gnu/store} directory---whereas users do not. The recommended
  2010. setup also has the daemon perform builds in chroots, under a specific
  2011. build users, to minimize interference with the rest of the system.
  2012. @cindex derivation
  2013. Lower-level APIs are available to interact with the daemon and the
  2014. store. To instruct the daemon to perform a build action, users actually
  2015. provide it with a @dfn{derivation}. A derivation is a low-level
  2016. representation of the build actions to be taken, and the environment in
  2017. which they should occur---derivations are to package definitions what
  2018. assembly is to C programs. The term ``derivation'' comes from the fact
  2019. that build results @emph{derive} from them.
  2020. This chapter describes all these APIs in turn, starting from high-level
  2021. package definitions.
  2022. @menu
  2023. * Defining Packages:: Defining new packages.
  2024. * Build Systems:: Specifying how packages are built.
  2025. * The Store:: Manipulating the package store.
  2026. * Derivations:: Low-level interface to package derivations.
  2027. * The Store Monad:: Purely functional interface to the store.
  2028. * G-Expressions:: Manipulating build expressions.
  2029. @end menu
  2030. @node Defining Packages
  2031. @section Defining Packages
  2032. The high-level interface to package definitions is implemented in the
  2033. @code{(guix packages)} and @code{(guix build-system)} modules. As an
  2034. example, the package definition, or @dfn{recipe}, for the GNU Hello
  2035. package looks like this:
  2036. @example
  2037. (define-module (gnu packages hello)
  2038. #:use-module (guix packages)
  2039. #:use-module (guix download)
  2040. #:use-module (guix build-system gnu)
  2041. #:use-module (guix licenses)
  2042. #:use-module (gnu packages gawk))
  2043. (define-public hello
  2044. (package
  2045. (name "hello")
  2046. (version "2.10")
  2047. (source (origin
  2048. (method url-fetch)
  2049. (uri (string-append "mirror://gnu/hello/hello-" version
  2050. ".tar.gz"))
  2051. (sha256
  2052. (base32
  2053. "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
  2054. (build-system gnu-build-system)
  2055. (arguments '(#:configure-flags '("--enable-silent-rules")))
  2056. (inputs `(("gawk" ,gawk)))
  2057. (synopsis "Hello, GNU world: An example GNU package")
  2058. (description "Guess what GNU Hello prints!")
  2059. (home-page "http://www.gnu.org/software/hello/")
  2060. (license gpl3+)))
  2061. @end example
  2062. @noindent
  2063. Without being a Scheme expert, the reader may have guessed the meaning
  2064. of the various fields here. This expression binds the variable
  2065. @code{hello} to a @code{<package>} object, which is essentially a record
  2066. (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
  2067. This package object can be inspected using procedures found in the
  2068. @code{(guix packages)} module; for instance, @code{(package-name hello)}
  2069. returns---surprise!---@code{"hello"}.
  2070. With luck, you may be able to import part or all of the definition of
  2071. the package you are interested in from another repository, using the
  2072. @code{guix import} command (@pxref{Invoking guix import}).
  2073. In the example above, @var{hello} is defined in a module of its own,
  2074. @code{(gnu packages hello)}. Technically, this is not strictly
  2075. necessary, but it is convenient to do so: all the packages defined in
  2076. modules under @code{(gnu packages @dots{})} are automatically known to
  2077. the command-line tools (@pxref{Package Modules}).
  2078. There are a few points worth noting in the above package definition:
  2079. @itemize
  2080. @item
  2081. The @code{source} field of the package is an @code{<origin>} object
  2082. (@pxref{origin Reference}, for the complete reference).
  2083. Here, the @code{url-fetch} method from @code{(guix download)} is used,
  2084. meaning that the source is a file to be downloaded over FTP or HTTP.
  2085. The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
  2086. the GNU mirrors defined in @code{(guix download)}.
  2087. The @code{sha256} field specifies the expected SHA256 hash of the file
  2088. being downloaded. It is mandatory, and allows Guix to check the
  2089. integrity of the file. The @code{(base32 @dots{})} form introduces the
  2090. base32 representation of the hash. You can obtain this information with
  2091. @code{guix download} (@pxref{Invoking guix download}) and @code{guix
  2092. hash} (@pxref{Invoking guix hash}).
  2093. @cindex patches
  2094. When needed, the @code{origin} form can also have a @code{patches} field
  2095. listing patches to be applied, and a @code{snippet} field giving a
  2096. Scheme expression to modify the source code.
  2097. @item
  2098. @cindex GNU Build System
  2099. The @code{build-system} field specifies the procedure to build the
  2100. package (@pxref{Build Systems}). Here, @var{gnu-build-system}
  2101. represents the familiar GNU Build System, where packages may be
  2102. configured, built, and installed with the usual @code{./configure &&
  2103. make && make check && make install} command sequence.
  2104. @item
  2105. The @code{arguments} field specifies options for the build system
  2106. (@pxref{Build Systems}). Here it is interpreted by
  2107. @var{gnu-build-system} as a request run @file{configure} with the
  2108. @code{--enable-silent-rules} flag.
  2109. @cindex quote
  2110. @cindex quoting
  2111. @findex '
  2112. @findex quote
  2113. What about these quote (@code{'}) characters? They are Scheme syntax to
  2114. introduce a literal list; @code{'} is synonymous with @code{quote}.
  2115. @xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual},
  2116. for details. Here the value of the @code{arguments} field is a list of
  2117. arguments passed to the build system down the road, as with @code{apply}
  2118. (@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference
  2119. Manual}).
  2120. The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword}
  2121. (@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and
  2122. @code{#:configure-flags} is a keyword used to pass a keyword argument
  2123. to the build system (@pxref{Coding With Keywords,,, guile, GNU Guile
  2124. Reference Manual}).
  2125. @item
  2126. The @code{inputs} field specifies inputs to the build process---i.e.,
  2127. build-time or run-time dependencies of the package. Here, we define an
  2128. input called @code{"gawk"} whose value is that of the @var{gawk}
  2129. variable; @var{gawk} is itself bound to a @code{<package>} object.
  2130. @cindex backquote (quasiquote)
  2131. @findex `
  2132. @findex quasiquote
  2133. @cindex comma (unquote)
  2134. @findex ,
  2135. @findex unquote
  2136. @findex ,@@
  2137. @findex unquote-splicing
  2138. Again, @code{`} (a backquote, synonymous with @code{quasiquote}) allows
  2139. us to introduce a literal list in the @code{inputs} field, while
  2140. @code{,} (a comma, synonymous with @code{unquote}) allows us to insert a
  2141. value in that list (@pxref{Expression Syntax, unquote,, guile, GNU Guile
  2142. Reference Manual}).
  2143. Note that GCC, Coreutils, Bash, and other essential tools do not need to
  2144. be specified as inputs here. Instead, @var{gnu-build-system} takes care
  2145. of ensuring that they are present (@pxref{Build Systems}).
  2146. However, any other dependencies need to be specified in the
  2147. @code{inputs} field. Any dependency not specified here will simply be
  2148. unavailable to the build process, possibly leading to a build failure.
  2149. @end itemize
  2150. @xref{package Reference}, for a full description of possible fields.
  2151. Once a package definition is in place, the
  2152. package may actually be built using the @code{guix build} command-line
  2153. tool (@pxref{Invoking guix build}). You can easily jump back to the
  2154. package definition using the @command{guix edit} command
  2155. (@pxref{Invoking guix edit}).
  2156. @xref{Packaging Guidelines}, for
  2157. more information on how to test package definitions, and
  2158. @ref{Invoking guix lint}, for information on how to check a definition
  2159. for style conformance.
  2160. Finally, updating the package definition to a new upstream version
  2161. can be partly automated by the @command{guix refresh} command
  2162. (@pxref{Invoking guix refresh}).
  2163. Behind the scenes, a derivation corresponding to the @code{<package>}
  2164. object is first computed by the @code{package-derivation} procedure.
  2165. That derivation is stored in a @code{.drv} file under @file{/gnu/store}.
  2166. The build actions it prescribes may then be realized by using the
  2167. @code{build-derivations} procedure (@pxref{The Store}).
  2168. @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
  2169. Return the @code{<derivation>} object of @var{package} for @var{system}
  2170. (@pxref{Derivations}).
  2171. @var{package} must be a valid @code{<package>} object, and @var{system}
  2172. must be a string denoting the target system type---e.g.,
  2173. @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
  2174. must be a connection to the daemon, which operates on the store
  2175. (@pxref{The Store}).
  2176. @end deffn
  2177. @noindent
  2178. @cindex cross-compilation
  2179. Similarly, it is possible to compute a derivation that cross-builds a
  2180. package for some other system:
  2181. @deffn {Scheme Procedure} package-cross-derivation @var{store} @
  2182. @var{package} @var{target} [@var{system}]
  2183. Return the @code{<derivation>} object of @var{package} cross-built from
  2184. @var{system} to @var{target}.
  2185. @var{target} must be a valid GNU triplet denoting the target hardware
  2186. and operating system, such as @code{"mips64el-linux-gnu"}
  2187. (@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
  2188. Configure and Build System}).
  2189. @end deffn
  2190. @cindex package transformations
  2191. @cindex input rewriting
  2192. @cindex dependency tree rewriting
  2193. Packages can be manipulated in arbitrary ways. An example of a useful
  2194. transformation is @dfn{input rewriting}, whereby the dependency tree of
  2195. a package is rewritten by replacing specific inputs by others:
  2196. @deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
  2197. [@var{rewrite-name}]
  2198. Return a procedure that, when passed a package, replaces its direct and
  2199. indirect dependencies (but not its implicit inputs) according to
  2200. @var{replacements}. @var{replacements} is a list of package pairs; the
  2201. first element of each pair is the package to replace, and the second one
  2202. is the replacement.
  2203. Optionally, @var{rewrite-name} is a one-argument procedure that takes
  2204. the name of a package and returns its new name after rewrite.
  2205. @end deffn
  2206. @noindent
  2207. Consider this example:
  2208. @example
  2209. (define libressl-instead-of-openssl
  2210. ;; This is a procedure to replace OPENSSL by LIBRESSL,
  2211. ;; recursively.
  2212. (package-input-rewriting `((,openssl . ,libressl))))
  2213. (define git-with-libressl
  2214. (libressl-instead-of-openssl git))
  2215. @end example
  2216. @noindent
  2217. Here we first define a rewriting procedure that replaces @var{openssl}
  2218. with @var{libressl}. Then we use it to define a @dfn{variant} of the
  2219. @var{git} package that uses @var{libressl} instead of @var{openssl}.
  2220. This is exactly what the @option{--with-input} command-line option does
  2221. (@pxref{Package Transformation Options, @option{--with-input}}).
  2222. @menu
  2223. * package Reference :: The package data type.
  2224. * origin Reference:: The origin data type.
  2225. @end menu
  2226. @node package Reference
  2227. @subsection @code{package} Reference
  2228. This section summarizes all the options available in @code{package}
  2229. declarations (@pxref{Defining Packages}).
  2230. @deftp {Data Type} package
  2231. This is the data type representing a package recipe.
  2232. @table @asis
  2233. @item @code{name}
  2234. The name of the package, as a string.
  2235. @item @code{version}
  2236. The version of the package, as a string.
  2237. @item @code{source}
  2238. An object telling how the source code for the package should be
  2239. acquired. Most of the time, this is an @code{origin} object, which
  2240. denotes a file fetched from the Internet (@pxref{origin Reference}). It
  2241. can also be any other ``file-like'' object such as a @code{local-file},
  2242. which denotes a file from the local file system (@pxref{G-Expressions,
  2243. @code{local-file}}).
  2244. @item @code{build-system}
  2245. The build system that should be used to build the package (@pxref{Build
  2246. Systems}).
  2247. @item @code{arguments} (default: @code{'()})
  2248. The arguments that should be passed to the build system. This is a
  2249. list, typically containing sequential keyword-value pairs.
  2250. @item @code{inputs} (default: @code{'()})
  2251. @itemx @code{native-inputs} (default: @code{'()})
  2252. @itemx @code{propagated-inputs} (default: @code{'()})
  2253. @cindex inputs, of packages
  2254. These fields list dependencies of the package. Each one is a list of
  2255. tuples, where each tuple has a label for the input (a string) as its
  2256. first element, a package, origin, or derivation as its second element,
  2257. and optionally the name of the output thereof that should be used, which
  2258. defaults to @code{"out"} (@pxref{Packages with Multiple Outputs}, for
  2259. more on package outputs). For example, the list below specifies three
  2260. inputs:
  2261. @example
  2262. `(("libffi" ,libffi)
  2263. ("libunistring" ,libunistring)
  2264. ("glib:bin" ,glib "bin")) ;the "bin" output of Glib
  2265. @end example
  2266. @cindex cross compilation, package dependencies
  2267. The distinction between @code{native-inputs} and @code{inputs} is
  2268. necessary when considering cross-compilation. When cross-compiling,
  2269. dependencies listed in @code{inputs} are built for the @emph{target}
  2270. architecture; conversely, dependencies listed in @code{native-inputs}
  2271. are built for the architecture of the @emph{build} machine.
  2272. @code{native-inputs} is typically used to list tools needed at
  2273. build time, but not at run time, such as Autoconf, Automake, pkg-config,
  2274. Gettext, or Bison. @command{guix lint} can report likely mistakes in
  2275. this area (@pxref{Invoking guix lint}).
  2276. @anchor{package-propagated-inputs}
  2277. Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
  2278. specified packages will be automatically installed alongside the package
  2279. they belong to (@pxref{package-cmd-propagated-inputs, @command{guix
  2280. package}}, for information on how @command{guix package} deals with
  2281. propagated inputs.)
  2282. For example this is necessary when a C/C++ library needs headers of
  2283. another library to compile, or when a pkg-config file refers to another
  2284. one @i{via} its @code{Requires} field.
  2285. Another example where @code{propagated-inputs} is useful is for languages
  2286. that lack a facility to record the run-time search path akin to the
  2287. @code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and
  2288. more. To ensure that libraries written in those languages can find
  2289. library code they depend on at run time, run-time dependencies must be
  2290. listed in @code{propagated-inputs} rather than @code{inputs}.
  2291. @item @code{self-native-input?} (default: @code{#f})
  2292. This is a Boolean field telling whether the package should use itself as
  2293. a native input when cross-compiling.
  2294. @item @code{outputs} (default: @code{'("out")})
  2295. The list of output names of the package. @xref{Packages with Multiple
  2296. Outputs}, for typical uses of additional outputs.
  2297. @item @code{native-search-paths} (default: @code{'()})
  2298. @itemx @code{search-paths} (default: @code{'()})
  2299. A list of @code{search-path-specification} objects describing
  2300. search-path environment variables honored by the package.
  2301. @item @code{replacement} (default: @code{#f})
  2302. This must be either @code{#f} or a package object that will be used as a
  2303. @dfn{replacement} for this package. @xref{Security Updates, grafts},
  2304. for details.
  2305. @item @code{synopsis}
  2306. A one-line description of the package.
  2307. @item @code{description}
  2308. A more elaborate description of the package.
  2309. @item @code{license}
  2310. @cindex license, of packages
  2311. The license of the package; a value from @code{(guix licenses)},
  2312. or a list of such values.
  2313. @item @code{home-page}
  2314. The URL to the home-page of the package, as a string.
  2315. @item @code{supported-systems} (default: @var{%supported-systems})
  2316. The list of systems supported by the package, as strings of the form
  2317. @code{architecture-kernel}, for example @code{"x86_64-linux"}.
  2318. @item @code{maintainers} (default: @code{'()})
  2319. The list of maintainers of the package, as @code{maintainer} objects.
  2320. @item @code{location} (default: source location of the @code{package} form)
  2321. The source location of the package. It is useful to override this when
  2322. inheriting from another package, in which case this field is not
  2323. automatically corrected.
  2324. @end table
  2325. @end deftp
  2326. @node origin Reference
  2327. @subsection @code{origin} Reference
  2328. This section summarizes all the options available in @code{origin}
  2329. declarations (@pxref{Defining Packages}).
  2330. @deftp {Data Type} origin
  2331. This is the data type representing a source code origin.
  2332. @table @asis
  2333. @item @code{uri}
  2334. An object containing the URI of the source. The object type depends on
  2335. the @code{method} (see below). For example, when using the
  2336. @var{url-fetch} method of @code{(guix download)}, the valid @code{uri}
  2337. values are: a URL represented as a string, or a list thereof.
  2338. @item @code{method}
  2339. A procedure that handles the URI.
  2340. Examples include:
  2341. @table @asis
  2342. @item @var{url-fetch} from @code{(guix download)}
  2343. download a file from the HTTP, HTTPS, or FTP URL specified in the
  2344. @code{uri} field;
  2345. @vindex git-fetch
  2346. @item @var{git-fetch} from @code{(guix git-download)}
  2347. clone the Git version control repository, and check out the revision
  2348. specified in the @code{uri} field as a @code{git-reference} object; a
  2349. @code{git-reference} looks like this:
  2350. @example
  2351. (git-reference
  2352. (url "git://git.debian.org/git/pkg-shadow/shadow")
  2353. (commit "v4.1.5.1"))
  2354. @end example
  2355. @end table
  2356. @item @code{sha256}
  2357. A bytevector containing the SHA-256 hash of the source. Typically the
  2358. @code{base32} form is used here to generate the bytevector from a
  2359. base-32 string.
  2360. You can obtain this information using @code{guix download}
  2361. (@pxref{Invoking guix download}) or @code{guix hash} (@pxref{Invoking
  2362. guix hash}).
  2363. @item @code{file-name} (default: @code{#f})
  2364. The file name under which the source code should be saved. When this is
  2365. @code{#f}, a sensible default value will be used in most cases. In case
  2366. the source is fetched from a URL, the file name from the URL will be
  2367. used. For version control checkouts, it is recommended to provide the
  2368. file name explicitly because the default is not very descriptive.
  2369. @item @code{patches} (default: @code{'()})
  2370. A list of file names containing patches to be applied to the source.
  2371. This list of patches must be unconditional. In particular, it cannot
  2372. depend on the value of @code{%current-system} or
  2373. @code{%current-target-system}.
  2374. @item @code{snippet} (default: @code{#f})
  2375. A G-expression (@pxref{G-Expressions}) or S-expression that will be run
  2376. in the source directory. This is a convenient way to modify the source,
  2377. sometimes more convenient than a patch.
  2378. @item @code{patch-flags} (default: @code{'("-p1")})
  2379. A list of command-line flags that should be passed to the @code{patch}
  2380. command.
  2381. @item @code{patch-inputs} (default: @code{#f})
  2382. Input packages or derivations to the patching process. When this is
  2383. @code{#f}, the usual set of inputs necessary for patching are provided,
  2384. such as GNU@tie{}Patch.
  2385. @item @code{modules} (default: @code{'()})
  2386. A list of Guile modules that should be loaded during the patching
  2387. process and while running the code in the @code{snippet} field.
  2388. @item @code{patch-guile} (default: @code{#f})
  2389. The Guile package that should be used in the patching process. When
  2390. this is @code{#f}, a sensible default is used.
  2391. @end table
  2392. @end deftp
  2393. @node Build Systems
  2394. @section Build Systems
  2395. @cindex build system
  2396. Each package definition specifies a @dfn{build system} and arguments for
  2397. that build system (@pxref{Defining Packages}). This @code{build-system}
  2398. field represents the build procedure of the package, as well as implicit
  2399. dependencies of that build procedure.
  2400. Build systems are @code{<build-system>} objects. The interface to
  2401. create and manipulate them is provided by the @code{(guix build-system)}
  2402. module, and actual build systems are exported by specific modules.
  2403. @cindex bag (low-level package representation)
  2404. Under the hood, build systems first compile package objects to
  2405. @dfn{bags}. A @dfn{bag} is like a package, but with less
  2406. ornamentation---in other words, a bag is a lower-level representation of
  2407. a package, which includes all the inputs of that package, including some
  2408. that were implicitly added by the build system. This intermediate
  2409. representation is then compiled to a derivation (@pxref{Derivations}).
  2410. Build systems accept an optional list of @dfn{arguments}. In package
  2411. definitions, these are passed @i{via} the @code{arguments} field
  2412. (@pxref{Defining Packages}). They are typically keyword arguments
  2413. (@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
  2414. Guile Reference Manual}). The value of these arguments is usually
  2415. evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
  2416. by the daemon (@pxref{Derivations}).
  2417. The main build system is @var{gnu-build-system}, which implements the
  2418. standard build procedure for GNU and many other packages. It
  2419. is provided by the @code{(guix build-system gnu)} module.
  2420. @defvr {Scheme Variable} gnu-build-system
  2421. @var{gnu-build-system} represents the GNU Build System, and variants
  2422. thereof (@pxref{Configuration, configuration and makefile conventions,,
  2423. standards, GNU Coding Standards}).
  2424. @cindex build phases
  2425. In a nutshell, packages using it are configured, built, and installed with
  2426. the usual @code{./configure && make && make check && make install}
  2427. command sequence. In practice, a few additional steps are often needed.
  2428. All these steps are split up in separate @dfn{phases},
  2429. notably@footnote{Please see the @code{(guix build gnu-build-system)}
  2430. modules for more details about the build phases.}:
  2431. @table @code
  2432. @item unpack
  2433. Unpack the source tarball, and change the current directory to the
  2434. extracted source tree. If the source is actually a directory, copy it
  2435. to the build tree, and enter that directory.
  2436. @item patch-source-shebangs
  2437. Patch shebangs encountered in source files so they refer to the right
  2438. store file names. For instance, this changes @code{#!/bin/sh} to
  2439. @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
  2440. @item configure
  2441. Run the @file{configure} script with a number of default options, such
  2442. as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
  2443. by the @code{#:configure-flags} argument.
  2444. @item build
  2445. Run @code{make} with the list of flags specified with
  2446. @code{#:make-flags}. If the @code{#:parallel-build?} argument is true
  2447. (the default), build with @code{make -j}.
  2448. @item check
  2449. Run @code{make check}, or some other target specified with
  2450. @code{#:test-target}, unless @code{#:tests? #f} is passed. If the
  2451. @code{#:parallel-tests?} argument is true (the default), run @code{make
  2452. check -j}.
  2453. @item install
  2454. Run @code{make install} with the flags listed in @code{#:make-flags}.
  2455. @item patch-shebangs
  2456. Patch shebangs on the installed executable files.
  2457. @item strip
  2458. Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
  2459. is false), copying them to the @code{debug} output when available
  2460. (@pxref{Installing Debugging Files}).
  2461. @end table
  2462. @vindex %standard-phases
  2463. The build-side module @code{(guix build gnu-build-system)} defines
  2464. @var{%standard-phases} as the default list of build phases.
  2465. @var{%standard-phases} is a list of symbol/procedure pairs, where the
  2466. procedure implements the actual phase.
  2467. The list of phases used for a particular package can be changed with the
  2468. @code{#:phases} parameter. For instance, passing:
  2469. @example
  2470. #:phases (modify-phases %standard-phases (delete 'configure))
  2471. @end example
  2472. means that all the phases described above will be used, except the
  2473. @code{configure} phase.
  2474. In addition, this build system ensures that the ``standard'' environment
  2475. for GNU packages is available. This includes tools such as GCC, libc,
  2476. Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
  2477. build-system gnu)} module for a complete list). We call these the
  2478. @dfn{implicit inputs} of a package, because package definitions do not
  2479. have to mention them.
  2480. @end defvr
  2481. Other @code{<build-system>} objects are defined to support other
  2482. conventions and tools used by free software packages. They inherit most
  2483. of @var{gnu-build-system}, and differ mainly in the set of inputs
  2484. implicitly added to the build process, and in the list of phases
  2485. executed. Some of these build systems are listed below.
  2486. @defvr {Scheme Variable} ant-build-system
  2487. This variable is exported by @code{(guix build-system ant)}. It
  2488. implements the build procedure for Java packages that can be built with
  2489. @url{http://ant.apache.org/, Ant build tool}.
  2490. It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as
  2491. provided by the @code{icedtea} package to the set of inputs. Different
  2492. packages can be specified with the @code{#:ant} and @code{#:jdk}
  2493. parameters, respectively.
  2494. When the original package does not provide a suitable Ant build file,
  2495. the parameter @code{#:jar-name} can be used to generate a minimal Ant
  2496. build file @file{build.xml} with tasks to build the specified jar
  2497. archive.
  2498. The parameter @code{#:build-target} can be used to specify the Ant task
  2499. that should be run during the @code{build} phase. By default the
  2500. ``jar'' task will be run.
  2501. @end defvr
  2502. @defvr {Scheme Variable} asdf-build-system/source
  2503. @defvrx {Scheme Variable} asdf-build-system/sbcl
  2504. @defvrx {Scheme Variable} asdf-build-system/ecl
  2505. These variables, exported by @code{(guix build-system asdf)}, implement
  2506. build procedures for Common Lisp packages using
  2507. @url{https://common-lisp.net/project/asdf/, ``ASDF''}. ASDF is a system
  2508. definition facility for Common Lisp programs and libraries.
  2509. The @code{asdf-build-system/source} system installs the packages in
  2510. source form, and can be loaded using any common lisp implementation, via
  2511. ASDF. The others, such as @code{asdf-build-system/sbcl}, install binary
  2512. systems in the format which a particular implementation understands.
  2513. These build systems can also be used to produce executable programs, or
  2514. lisp images which contain a set of packages pre-loaded.
  2515. The build system uses naming conventions. For binary packages, the
  2516. package itself as well as its run-time dependencies should begin their
  2517. name with the lisp implementation, such as @code{sbcl-} for
  2518. @code{asdf-build-system/sbcl}. Beginning the input name with this
  2519. prefix will allow the build system to encode its location into the
  2520. resulting library, so that the input can be found at run-time.
  2521. If dependencies are used only for tests, it is convenient to use a
  2522. different prefix in order to avoid having a run-time dependency on such
  2523. systems. For example,
  2524. @example
  2525. (define-public sbcl-bordeaux-threads
  2526. (package
  2527. ...
  2528. (native-inputs `(("tests:cl-fiveam" ,sbcl-fiveam)))
  2529. ...))
  2530. @end example
  2531. Additionally, the corresponding source package should be labeled using
  2532. the same convention as python packages (see @ref{Python Modules}), using
  2533. the @code{cl-} prefix.
  2534. For binary packages, each system should be defined as a Guix package.
  2535. If one package @code{origin} contains several systems, package variants
  2536. can be created in order to build all the systems. Source packages,
  2537. which use @code{asdf-build-system/source}, may contain several systems.
  2538. In order to create executable programs and images, the build-side
  2539. procedures @code{build-program} and @code{build-image} can be used.
  2540. They should be called in a build phase after the @code{create-symlinks}
  2541. phase, so that the system which was just built can be used within the
  2542. resulting image. @code{build-program} requires a list of Common Lisp
  2543. expressions to be passed as the @code{#:entry-program} argument.
  2544. If the system is not defined within its own @code{.asd} file of the same
  2545. name, then the @code{#:asd-file} parameter should be used to specify
  2546. which file the system is defined in.
  2547. @end defvr
  2548. @defvr {Scheme Variable} cargo-build-system
  2549. @cindex Rust programming language
  2550. @cindex Cargo (Rust build system)
  2551. This variable is exported by @code{(guix build-system cargo)}. It
  2552. supports builds of packages using Cargo, the build tool of the
  2553. @uref{https://www.rust-lang.org, Rust programming language}.
  2554. In its @code{configure} phase, this build system replaces dependencies
  2555. specified in the @file{Carto.toml} file with inputs to the Guix package.
  2556. The @code{install} phase installs the binaries, and it also installs the
  2557. source code and @file{Cargo.toml} file.
  2558. @end defvr
  2559. @defvr {Scheme Variable} cmake-build-system
  2560. This variable is exported by @code{(guix build-system cmake)}. It
  2561. implements the build procedure for packages using the
  2562. @url{http://www.cmake.org, CMake build tool}.
  2563. It automatically adds the @code{cmake} package to the set of inputs.
  2564. Which package is used can be specified with the @code{#:cmake}
  2565. parameter.
  2566. The @code{#:configure-flags} parameter is taken as a list of flags
  2567. passed to the @command{cmake} command. The @code{#:build-type}
  2568. parameter specifies in abstract terms the flags passed to the compiler;
  2569. it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
  2570. debugging information''), which roughly means that code is compiled with
  2571. @code{-O2 -g}, as is the case for Autoconf-based packages by default.
  2572. @end defvr
  2573. @defvr {Scheme Variable} glib-or-gtk-build-system
  2574. This variable is exported by @code{(guix build-system glib-or-gtk)}. It
  2575. is intended for use with packages making use of GLib or GTK+.
  2576. This build system adds the following two phases to the ones defined by
  2577. @var{gnu-build-system}:
  2578. @table @code
  2579. @item glib-or-gtk-wrap
  2580. The phase @code{glib-or-gtk-wrap} ensures that programs in
  2581. @file{bin/} are able to find GLib ``schemas'' and
  2582. @uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
  2583. modules}. This is achieved by wrapping the programs in launch scripts
  2584. that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
  2585. environment variables.
  2586. It is possible to exclude specific package outputs from that wrapping
  2587. process by listing their names in the
  2588. @code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
  2589. when an output is known not to contain any GLib or GTK+ binaries, and
  2590. where wrapping would gratuitously add a dependency of that output on
  2591. GLib and GTK+.
  2592. @item glib-or-gtk-compile-schemas
  2593. The phase @code{glib-or-gtk-compile-schemas} makes sure that all
  2594. @uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
  2595. GSettings schemas} of GLib are compiled. Compilation is performed by the
  2596. @command{glib-compile-schemas} program. It is provided by the package
  2597. @code{glib:bin} which is automatically imported by the build system.
  2598. The @code{glib} package providing @command{glib-compile-schemas} can be
  2599. specified with the @code{#:glib} parameter.
  2600. @end table
  2601. Both phases are executed after the @code{install} phase.
  2602. @end defvr
  2603. @defvr {Scheme Variable} python-build-system
  2604. This variable is exported by @code{(guix build-system python)}. It
  2605. implements the more or less standard build procedure used by Python
  2606. packages, which consists in running @code{python setup.py build} and
  2607. then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
  2608. For packages that install stand-alone Python programs under @code{bin/},
  2609. it takes care of wrapping these programs so that their @code{PYTHONPATH}
  2610. environment variable points to all the Python libraries they depend on.
  2611. Which Python package is used to perform the build can be specified with
  2612. the @code{#:python} parameter. This is a useful way to force a package
  2613. to be built for a specific version of the Python interpreter, which
  2614. might be necessary if the package is only compatible with a single
  2615. interpreter version.
  2616. By default guix calls @code{setup.py} under control of
  2617. @code{setuptools}, much like @command{pip} does. Some packages are not
  2618. compatible with setuptools (and pip), thus you can disable this by
  2619. setting the @code{#:use-setuptools} parameter to @code{#f}.
  2620. @end defvr
  2621. @defvr {Scheme Variable} perl-build-system
  2622. This variable is exported by @code{(guix build-system perl)}. It
  2623. implements the standard build procedure for Perl packages, which either
  2624. consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
  2625. followed by @code{Build} and @code{Build install}; or in running
  2626. @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
  2627. @code{make} and @code{make install}, depending on which of
  2628. @code{Build.PL} or @code{Makefile.PL} is present in the package
  2629. distribution. Preference is given to the former if both @code{Build.PL}
  2630. and @code{Makefile.PL} exist in the package distribution. This
  2631. preference can be reversed by specifying @code{#t} for the
  2632. @code{#:make-maker?} parameter.
  2633. The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
  2634. passes flags specified by the @code{#:make-maker-flags} or
  2635. @code{#:module-build-flags} parameter, respectively.
  2636. Which Perl package is used can be specified with @code{#:perl}.
  2637. @end defvr
  2638. @defvr {Scheme Variable} r-build-system
  2639. This variable is exported by @code{(guix build-system r)}. It
  2640. implements the build procedure used by @uref{http://r-project.org, R}
  2641. packages, which essentially is little more than running @code{R CMD
  2642. INSTALL --library=/gnu/store/@dots{}} in an environment where
  2643. @code{R_LIBS_SITE} contains the paths to all R package inputs. Tests
  2644. are run after installation using the R function
  2645. @code{tools::testInstalledPackage}.
  2646. @end defvr
  2647. @defvr {Scheme Variable} ruby-build-system
  2648. This variable is exported by @code{(guix build-system ruby)}. It
  2649. implements the RubyGems build procedure used by Ruby packages, which
  2650. involves running @code{gem build} followed by @code{gem install}.
  2651. The @code{source} field of a package that uses this build system
  2652. typically references a gem archive, since this is the format that Ruby
  2653. developers use when releasing their software. The build system unpacks
  2654. the gem archive, potentially patches the source, runs the test suite,
  2655. repackages the gem, and installs it. Additionally, directories and
  2656. tarballs may be referenced to allow building unreleased gems from Git or
  2657. a traditional source release tarball.
  2658. Which Ruby package is used can be specified with the @code{#:ruby}
  2659. parameter. A list of additional flags to be passed to the @command{gem}
  2660. command can be specified with the @code{#:gem-flags} parameter.
  2661. @end defvr
  2662. @defvr {Scheme Variable} waf-build-system
  2663. This variable is exported by @code{(guix build-system waf)}. It
  2664. implements a build procedure around the @code{waf} script. The common
  2665. phases---@code{configure}, @code{build}, and @code{install}---are
  2666. implemented by passing their names as arguments to the @code{waf}
  2667. script.
  2668. The @code{waf} script is executed by the Python interpreter. Which
  2669. Python package is used to run the script can be specified with the
  2670. @code{#:python} parameter.
  2671. @end defvr
  2672. @defvr {Scheme Variable} haskell-build-system
  2673. This variable is exported by @code{(guix build-system haskell)}. It
  2674. implements the Cabal build procedure used by Haskell packages, which
  2675. involves running @code{runhaskell Setup.hs configure
  2676. --prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.
  2677. Instead of installing the package by running @code{runhaskell Setup.hs
  2678. install}, to avoid trying to register libraries in the read-only
  2679. compiler store directory, the build system uses @code{runhaskell
  2680. Setup.hs copy}, followed by @code{runhaskell Setup.hs register}. In
  2681. addition, the build system generates the package documentation by
  2682. running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f}
  2683. is passed. Optional Haddock parameters can be passed with the help of
  2684. the @code{#:haddock-flags} parameter. If the file @code{Setup.hs} is
  2685. not found, the build system looks for @code{Setup.lhs} instead.
  2686. Which Haskell compiler is used can be specified with the @code{#:haskell}
  2687. parameter which defaults to @code{ghc}.
  2688. @end defvr
  2689. @defvr {Scheme Variable} emacs-build-system
  2690. This variable is exported by @code{(guix build-system emacs)}. It
  2691. implements an installation procedure similar to the packaging system
  2692. of Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
  2693. It first creates the @code{@var{package}-autoloads.el} file, then it
  2694. byte compiles all Emacs Lisp files. Differently from the Emacs
  2695. packaging system, the Info documentation files are moved to the standard
  2696. documentation directory and the @file{dir} file is deleted. Each
  2697. package is installed in its own directory under
  2698. @file{share/emacs/site-lisp/guix.d}.
  2699. @end defvr
  2700. Lastly, for packages that do not need anything as sophisticated, a
  2701. ``trivial'' build system is provided. It is trivial in the sense that
  2702. it provides basically no support: it does not pull any implicit inputs,
  2703. and does not have a notion of build phases.
  2704. @defvr {Scheme Variable} trivial-build-system
  2705. This variable is exported by @code{(guix build-system trivial)}.
  2706. This build system requires a @code{#:builder} argument. This argument
  2707. must be a Scheme expression that builds the package output(s)---as
  2708. with @code{build-expression->derivation} (@pxref{Derivations,
  2709. @code{build-expression->derivation}}).
  2710. @end defvr
  2711. @node The Store
  2712. @section The Store
  2713. @cindex store
  2714. @cindex store items
  2715. @cindex store paths
  2716. Conceptually, the @dfn{store} is the place where derivations that have
  2717. been built successfully are stored---by default, @file{/gnu/store}.
  2718. Sub-directories in the store are referred to as @dfn{store items} or
  2719. sometimes @dfn{store paths}. The store has an associated database that
  2720. contains information such as the store paths referred to by each store
  2721. path, and the list of @emph{valid} store items---results of successful
  2722. builds. This database resides in @file{@var{localstatedir}/guix/db},
  2723. where @var{localstatedir} is the state directory specified @i{via}
  2724. @option{--localstatedir} at configure time, usually @file{/var}.
  2725. The store is @emph{always} accessed by the daemon on behalf of its clients
  2726. (@pxref{Invoking guix-daemon}). To manipulate the store, clients
  2727. connect to the daemon over a Unix-domain socket, send requests to it,
  2728. and read the result---these are remote procedure calls, or RPCs.
  2729. @quotation Note
  2730. Users must @emph{never} modify files under @file{/gnu/store} directly.
  2731. This would lead to inconsistencies and break the immutability
  2732. assumptions of Guix's functional model (@pxref{Introduction}).
  2733. @xref{Invoking guix gc, @command{guix gc --verify}}, for information on
  2734. how to check the integrity of the store and attempt recovery from
  2735. accidental modifications.
  2736. @end quotation
  2737. The @code{(guix store)} module provides procedures to connect to the
  2738. daemon, and to perform RPCs. These are described below.
  2739. @deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
  2740. Connect to the daemon over the Unix-domain socket at @var{file}. When
  2741. @var{reserve-space?} is true, instruct it to reserve a little bit of
  2742. extra space on the file system so that the garbage collector can still
  2743. operate should the disk become full. Return a server object.
  2744. @var{file} defaults to @var{%default-socket-path}, which is the normal
  2745. location given the options that were passed to @command{configure}.
  2746. @end deffn
  2747. @deffn {Scheme Procedure} close-connection @var{server}
  2748. Close the connection to @var{server}.
  2749. @end deffn
  2750. @defvr {Scheme Variable} current-build-output-port
  2751. This variable is bound to a SRFI-39 parameter, which refers to the port
  2752. where build and error logs sent by the daemon should be written.
  2753. @end defvr
  2754. Procedures that make RPCs all take a server object as their first
  2755. argument.
  2756. @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
  2757. @cindex invalid store items
  2758. Return @code{#t} when @var{path} designates a valid store item and
  2759. @code{#f} otherwise (an invalid item may exist on disk but still be
  2760. invalid, for instance because it is the result of an aborted or failed
  2761. build.)
  2762. A @code{&nix-protocol-error} condition is raised if @var{path} is not
  2763. prefixed by the store directory (@file{/gnu/store}).
  2764. @end deffn
  2765. @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
  2766. Add @var{text} under file @var{name} in the store, and return its store
  2767. path. @var{references} is the list of store paths referred to by the
  2768. resulting store path.
  2769. @end deffn
  2770. @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
  2771. Build @var{derivations} (a list of @code{<derivation>} objects or
  2772. derivation paths), and return when the worker is done building them.
  2773. Return @code{#t} on success.
  2774. @end deffn
  2775. Note that the @code{(guix monads)} module provides a monad as well as
  2776. monadic versions of the above procedures, with the goal of making it
  2777. more convenient to work with code that accesses the store (@pxref{The
  2778. Store Monad}).
  2779. @c FIXME
  2780. @i{This section is currently incomplete.}
  2781. @node Derivations
  2782. @section Derivations
  2783. @cindex derivations
  2784. Low-level build actions and the environment in which they are performed
  2785. are represented by @dfn{derivations}. A derivation contains the
  2786. following pieces of information:
  2787. @itemize
  2788. @item
  2789. The outputs of the derivation---derivations produce at least one file or
  2790. directory in the store, but may produce more.
  2791. @item
  2792. The inputs of the derivations, which may be other derivations or plain
  2793. files in the store (patches, build scripts, etc.)
  2794. @item
  2795. The system type targeted by the derivation---e.g., @code{x86_64-linux}.
  2796. @item
  2797. The file name of a build script in the store, along with the arguments
  2798. to be passed.
  2799. @item
  2800. A list of environment variables to be defined.
  2801. @end itemize
  2802. @cindex derivation path
  2803. Derivations allow clients of the daemon to communicate build actions to
  2804. the store. They exist in two forms: as an in-memory representation,
  2805. both on the client- and daemon-side, and as files in the store whose
  2806. name end in @code{.drv}---these files are referred to as @dfn{derivation
  2807. paths}. Derivations paths can be passed to the @code{build-derivations}
  2808. procedure to perform the build actions they prescribe (@pxref{The
  2809. Store}).
  2810. The @code{(guix derivations)} module provides a representation of
  2811. derivations as Scheme objects, along with procedures to create and
  2812. otherwise manipulate derivations. The lowest-level primitive to create
  2813. a derivation is the @code{derivation} procedure:
  2814. @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
  2815. @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
  2816. [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
  2817. [#:system (%current-system)] [#:references-graphs #f] @
  2818. [#:allowed-references #f] [#:disallowed-references #f] @
  2819. [#:leaked-env-vars #f] [#:local-build? #f] @
  2820. [#:substitutable? #t]
  2821. Build a derivation with the given arguments, and return the resulting
  2822. @code{<derivation>} object.
  2823. When @var{hash} and @var{hash-algo} are given, a
  2824. @dfn{fixed-output derivation} is created---i.e., one whose result is
  2825. known in advance, such as a file download. If, in addition,
  2826. @var{recursive?} is true, then that fixed output may be an executable
  2827. file or a directory and @var{hash} must be the hash of an archive
  2828. containing this output.
  2829. When @var{references-graphs} is true, it must be a list of file
  2830. name/store path pairs. In that case, the reference graph of each store
  2831. path is exported in the build environment in the corresponding file, in
  2832. a simple text format.
  2833. When @var{allowed-references} is true, it must be a list of store items
  2834. or outputs that the derivation's output may refer to. Likewise,
  2835. @var{disallowed-references}, if true, must be a list of things the
  2836. outputs may @emph{not} refer to.
  2837. When @var{leaked-env-vars} is true, it must be a list of strings
  2838. denoting environment variables that are allowed to ``leak'' from the
  2839. daemon's environment to the build environment. This is only applicable
  2840. to fixed-output derivations---i.e., when @var{hash} is true. The main
  2841. use is to allow variables such as @code{http_proxy} to be passed to
  2842. derivations that download files.
  2843. When @var{local-build?} is true, declare that the derivation is not a
  2844. good candidate for offloading and should rather be built locally
  2845. (@pxref{Daemon Offload Setup}). This is the case for small derivations
  2846. where the costs of data transfers would outweigh the benefits.
  2847. When @var{substitutable?} is false, declare that substitutes of the
  2848. derivation's output should not be used (@pxref{Substitutes}). This is
  2849. useful, for instance, when building packages that capture details of the
  2850. host CPU instruction set.
  2851. @end deffn
  2852. @noindent
  2853. Here's an example with a shell script as its builder, assuming
  2854. @var{store} is an open connection to the daemon, and @var{bash} points
  2855. to a Bash executable in the store:
  2856. @lisp
  2857. (use-modules (guix utils)
  2858. (guix store)
  2859. (guix derivations))
  2860. (let ((builder ; add the Bash script to the store
  2861. (add-text-to-store store "my-builder.sh"
  2862. "echo hello world > $out\n" '())))
  2863. (derivation store "foo"
  2864. bash `("-e" ,builder)
  2865. #:inputs `((,bash) (,builder))
  2866. #:env-vars '(("HOME" . "/homeless"))))
  2867. @result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
  2868. @end lisp
  2869. As can be guessed, this primitive is cumbersome to use directly. A
  2870. better approach is to write build scripts in Scheme, of course! The
  2871. best course of action for that is to write the build code as a
  2872. ``G-expression'', and to pass it to @code{gexp->derivation}. For more
  2873. information, @pxref{G-Expressions}.
  2874. Once upon a time, @code{gexp->derivation} did not exist and constructing
  2875. derivations with build code written in Scheme was achieved with
  2876. @code{build-expression->derivation}, documented below. This procedure
  2877. is now deprecated in favor of the much nicer @code{gexp->derivation}.
  2878. @deffn {Scheme Procedure} build-expression->derivation @var{store} @
  2879. @var{name} @var{exp} @
  2880. [#:system (%current-system)] [#:inputs '()] @
  2881. [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
  2882. [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
  2883. [#:references-graphs #f] [#:allowed-references #f] @
  2884. [#:disallowed-references #f] @
  2885. [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f]
  2886. Return a derivation that executes Scheme expression @var{exp} as a
  2887. builder for derivation @var{name}. @var{inputs} must be a list of
  2888. @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
  2889. @code{"out"} is assumed. @var{modules} is a list of names of Guile
  2890. modules from the current search path to be copied in the store,
  2891. compiled, and made available in the load path during the execution of
  2892. @var{exp}---e.g., @code{((guix build utils) (guix build
  2893. gnu-build-system))}.
  2894. @var{exp} is evaluated in an environment where @code{%outputs} is bound
  2895. to a list of output/path pairs, and where @code{%build-inputs} is bound
  2896. to a list of string/output-path pairs made from @var{inputs}.
  2897. Optionally, @var{env-vars} is a list of string pairs specifying the name
  2898. and value of environment variables visible to the builder. The builder
  2899. terminates by passing the result of @var{exp} to @code{exit}; thus, when
  2900. @var{exp} returns @code{#f}, the build is considered to have failed.
  2901. @var{exp} is built using @var{guile-for-build} (a derivation). When
  2902. @var{guile-for-build} is omitted or is @code{#f}, the value of the
  2903. @code{%guile-for-build} fluid is used instead.
  2904. See the @code{derivation} procedure for the meaning of
  2905. @var{references-graphs}, @var{allowed-references},
  2906. @var{disallowed-references}, @var{local-build?}, and
  2907. @var{substitutable?}.
  2908. @end deffn
  2909. @noindent
  2910. Here's an example of a single-output derivation that creates a directory
  2911. containing one file:
  2912. @lisp
  2913. (let ((builder '(let ((out (assoc-ref %outputs "out")))
  2914. (mkdir out) ; create /gnu/store/@dots{}-goo
  2915. (call-with-output-file (string-append out "/test")
  2916. (lambda (p)
  2917. (display '(hello guix) p))))))
  2918. (build-expression->derivation store "goo" builder))
  2919. @result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
  2920. @end lisp
  2921. @node The Store Monad
  2922. @section The Store Monad
  2923. @cindex monad
  2924. The procedures that operate on the store described in the previous
  2925. sections all take an open connection to the build daemon as their first
  2926. argument. Although the underlying model is functional, they either have
  2927. side effects or depend on the current state of the store.
  2928. The former is inconvenient: the connection to the build daemon has to be
  2929. carried around in all those functions, making it impossible to compose
  2930. functions that do not take that parameter with functions that do. The
  2931. latter can be problematic: since store operations have side effects
  2932. and/or depend on external state, they have to be properly sequenced.
  2933. @cindex monadic values
  2934. @cindex monadic functions
  2935. This is where the @code{(guix monads)} module comes in. This module
  2936. provides a framework for working with @dfn{monads}, and a particularly
  2937. useful monad for our uses, the @dfn{store monad}. Monads are a
  2938. construct that allows two things: associating ``context'' with values
  2939. (in our case, the context is the store), and building sequences of
  2940. computations (here computations include accesses to the store). Values
  2941. in a monad---values that carry this additional context---are called
  2942. @dfn{monadic values}; procedures that return such values are called
  2943. @dfn{monadic procedures}.
  2944. Consider this ``normal'' procedure:
  2945. @example
  2946. (define (sh-symlink store)
  2947. ;; Return a derivation that symlinks the 'bash' executable.
  2948. (let* ((drv (package-derivation store bash))
  2949. (out (derivation->output-path drv))
  2950. (sh (string-append out "/bin/bash")))
  2951. (build-expression->derivation store "sh"
  2952. `(symlink ,sh %output))))
  2953. @end example
  2954. Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten
  2955. as a monadic function:
  2956. @example
  2957. (define (sh-symlink)
  2958. ;; Same, but return a monadic value.
  2959. (mlet %store-monad ((drv (package->derivation bash)))
  2960. (gexp->derivation "sh"
  2961. #~(symlink (string-append #$drv "/bin/bash")
  2962. #$output))))
  2963. @end example
  2964. There are several things to note in the second version: the @code{store}
  2965. parameter is now implicit and is ``threaded'' in the calls to the
  2966. @code{package->derivation} and @code{gexp->derivation} monadic
  2967. procedures, and the monadic value returned by @code{package->derivation}
  2968. is @dfn{bound} using @code{mlet} instead of plain @code{let}.
  2969. As it turns out, the call to @code{package->derivation} can even be
  2970. omitted since it will take place implicitly, as we will see later
  2971. (@pxref{G-Expressions}):
  2972. @example
  2973. (define (sh-symlink)
  2974. (gexp->derivation "sh"
  2975. #~(symlink (string-append #$bash "/bin/bash")
  2976. #$output)))
  2977. @end example
  2978. @c See
  2979. @c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/>
  2980. @c for the funny quote.
  2981. Calling the monadic @code{sh-symlink} has no effect. As someone once
  2982. said, ``you exit a monad like you exit a building on fire: by running''.
  2983. So, to exit the monad and get the desired effect, one must use
  2984. @code{run-with-store}:
  2985. @example
  2986. (run-with-store (open-connection) (sh-symlink))
  2987. @result{} /gnu/store/...-sh-symlink
  2988. @end example
  2989. Note that the @code{(guix monad-repl)} module extends the Guile REPL with
  2990. new ``meta-commands'' to make it easier to deal with monadic procedures:
  2991. @code{run-in-store}, and @code{enter-store-monad}. The former is used
  2992. to ``run'' a single monadic value through the store:
  2993. @example
  2994. scheme@@(guile-user)> ,run-in-store (package->derivation hello)
  2995. $1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
  2996. @end example
  2997. The latter enters a recursive REPL, where all the return values are
  2998. automatically run through the store:
  2999. @example
  3000. scheme@@(guile-user)> ,enter-store-monad
  3001. store-monad@@(guile-user) [1]> (package->derivation hello)
  3002. $2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
  3003. store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
  3004. $3 = "/gnu/store/@dots{}-foo"
  3005. store-monad@@(guile-user) [1]> ,q
  3006. scheme@@(guile-user)>
  3007. @end example
  3008. @noindent
  3009. Note that non-monadic values cannot be returned in the
  3010. @code{store-monad} REPL.
  3011. The main syntactic forms to deal with monads in general are provided by
  3012. the @code{(guix monads)} module and are described below.
  3013. @deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
  3014. Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
  3015. in @var{monad}.
  3016. @end deffn
  3017. @deffn {Scheme Syntax} return @var{val}
  3018. Return a monadic value that encapsulates @var{val}.
  3019. @end deffn
  3020. @deffn {Scheme Syntax} >>= @var{mval} @var{mproc} ...
  3021. @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
  3022. procedures @var{mproc}@dots{}@footnote{This operation is commonly
  3023. referred to as ``bind'', but that name denotes an unrelated procedure in
  3024. Guile. Thus we use this somewhat cryptic symbol inherited from the
  3025. Haskell language.}. There can be one @var{mproc} or several of them, as
  3026. in this example:
  3027. @example
  3028. (run-with-state
  3029. (with-monad %state-monad
  3030. (>>= (return 1)
  3031. (lambda (x) (return (+ 1 x)))
  3032. (lambda (x) (return (* 2 x)))))
  3033. 'some-state)
  3034. @result{} 4
  3035. @result{} some-state
  3036. @end example
  3037. @end deffn
  3038. @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
  3039. @var{body} ...
  3040. @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
  3041. @var{body} ...
  3042. Bind the variables @var{var} to the monadic values @var{mval} in
  3043. @var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the
  3044. ``normal'' value @var{val}, as per @code{let}.
  3045. @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
  3046. (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
  3047. @end deffn
  3048. @deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
  3049. Bind @var{mexp} and the following monadic expressions in sequence,
  3050. returning the result of the last expression.
  3051. This is akin to @code{mlet}, except that the return values of the
  3052. monadic expressions are ignored. In that sense, it is analogous to
  3053. @code{begin}, but applied to monadic expressions.
  3054. @end deffn
  3055. @cindex state monad
  3056. The @code{(guix monads)} module provides the @dfn{state monad}, which
  3057. allows an additional value---the state---to be @emph{threaded} through
  3058. monadic procedure calls.
  3059. @defvr {Scheme Variable} %state-monad
  3060. The state monad. Procedures in the state monad can access and change
  3061. the state that is threaded.
  3062. Consider the example below. The @code{square} procedure returns a value
  3063. in the state monad. It returns the square of its argument, but also
  3064. increments the current state value:
  3065. @example
  3066. (define (square x)
  3067. (mlet %state-monad ((count (current-state)))
  3068. (mbegin %state-monad
  3069. (set-current-state (+ 1 count))
  3070. (return (* x x)))))
  3071. (run-with-state (sequence %state-monad (map square (iota 3))) 0)
  3072. @result{} (0 1 4)
  3073. @result{} 3
  3074. @end example
  3075. When ``run'' through @var{%state-monad}, we obtain that additional state
  3076. value, which is the number of @code{square} calls.
  3077. @end defvr
  3078. @deffn {Monadic Procedure} current-state
  3079. Return the current state as a monadic value.
  3080. @end deffn
  3081. @deffn {Monadic Procedure} set-current-state @var{value}
  3082. Set the current state to @var{value} and return the previous state as a
  3083. monadic value.
  3084. @end deffn
  3085. @deffn {Monadic Procedure} state-push @var{value}
  3086. Push @var{value} to the current state, which is assumed to be a list,
  3087. and return the previous state as a monadic value.
  3088. @end deffn
  3089. @deffn {Monadic Procedure} state-pop
  3090. Pop a value from the current state and return it as a monadic value.
  3091. The state is assumed to be a list.
  3092. @end deffn
  3093. @deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}]
  3094. Run monadic value @var{mval} starting with @var{state} as the initial
  3095. state. Return two values: the resulting value, and the resulting state.
  3096. @end deffn
  3097. The main interface to the store monad, provided by the @code{(guix
  3098. store)} module, is as follows.
  3099. @defvr {Scheme Variable} %store-monad
  3100. The store monad---an alias for @var{%state-monad}.
  3101. Values in the store monad encapsulate accesses to the store. When its
  3102. effect is needed, a value of the store monad must be ``evaluated'' by
  3103. passing it to the @code{run-with-store} procedure (see below.)
  3104. @end defvr
  3105. @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
  3106. Run @var{mval}, a monadic value in the store monad, in @var{store}, an
  3107. open store connection.
  3108. @end deffn
  3109. @deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}]
  3110. Return as a monadic value the absolute file name in the store of the file
  3111. containing @var{text}, a string. @var{references} is a list of store items that the
  3112. resulting text file refers to; it defaults to the empty list.
  3113. @end deffn
  3114. @deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
  3115. [#:recursive? #t] [#:select? (const #t)]
  3116. Return the name of @var{file} once interned in the store. Use
  3117. @var{name} as its store name, or the basename of @var{file} if
  3118. @var{name} is omitted.
  3119. When @var{recursive?} is true, the contents of @var{file} are added
  3120. recursively; if @var{file} designates a flat file and @var{recursive?}
  3121. is true, its contents are added, and its permission bits are kept.
  3122. When @var{recursive?} is true, call @code{(@var{select?} @var{file}
  3123. @var{stat})} for each directory entry, where @var{file} is the entry's
  3124. absolute file name and @var{stat} is the result of @code{lstat}; exclude
  3125. entries for which @var{select?} does not return true.
  3126. The example below adds a file to the store, under two different names:
  3127. @example
  3128. (run-with-store (open-connection)
  3129. (mlet %store-monad ((a (interned-file "README"))
  3130. (b (interned-file "README" "LEGU-MIN")))
  3131. (return (list a b))))
  3132. @result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
  3133. @end example
  3134. @end deffn
  3135. The @code{(guix packages)} module exports the following package-related
  3136. monadic procedures:
  3137. @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
  3138. [#:system (%current-system)] [#:target #f] @
  3139. [#:output "out"]
  3140. Return as a monadic
  3141. value in the absolute file name of @var{file} within the @var{output}
  3142. directory of @var{package}. When @var{file} is omitted, return the name
  3143. of the @var{output} directory of @var{package}. When @var{target} is
  3144. true, use it as a cross-compilation target triplet.
  3145. @end deffn
  3146. @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
  3147. @deffnx {Monadic Procedure} package->cross-derivation @var{package} @
  3148. @var{target} [@var{system}]
  3149. Monadic version of @code{package-derivation} and
  3150. @code{package-cross-derivation} (@pxref{Defining Packages}).
  3151. @end deffn
  3152. @node G-Expressions
  3153. @section G-Expressions
  3154. @cindex G-expression
  3155. @cindex build code quoting
  3156. So we have ``derivations'', which represent a sequence of build actions
  3157. to be performed to produce an item in the store (@pxref{Derivations}).
  3158. These build actions are performed when asking the daemon to actually
  3159. build the derivations; they are run by the daemon in a container
  3160. (@pxref{Invoking guix-daemon}).
  3161. @cindex strata of code
  3162. It should come as no surprise that we like to write these build actions
  3163. in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
  3164. code@footnote{The term @dfn{stratum} in this context was coined by
  3165. Manuel Serrano et al.@: in the context of their work on Hop. Oleg
  3166. Kiselyov, who has written insightful
  3167. @url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
  3168. on this topic}, refers to this kind of code generation as
  3169. @dfn{staging}.}: the ``host code''---code that defines packages, talks
  3170. to the daemon, etc.---and the ``build code''---code that actually
  3171. performs build actions, such as making directories, invoking
  3172. @command{make}, etc.
  3173. To describe a derivation and its build actions, one typically needs to
  3174. embed build code inside host code. It boils down to manipulating build
  3175. code as data, and the homoiconicity of Scheme---code has a direct
  3176. representation as data---comes in handy for that. But we need more than
  3177. the normal @code{quasiquote} mechanism in Scheme to construct build
  3178. expressions.
  3179. The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
  3180. S-expressions adapted to build expressions. G-expressions, or
  3181. @dfn{gexps}, consist essentially of three syntactic forms: @code{gexp},
  3182. @code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
  3183. @code{#$}, and @code{#$@@}), which are comparable to
  3184. @code{quasiquote}, @code{unquote}, and @code{unquote-splicing},
  3185. respectively (@pxref{Expression Syntax, @code{quasiquote},, guile,
  3186. GNU Guile Reference Manual}). However, there are major differences:
  3187. @itemize
  3188. @item
  3189. Gexps are meant to be written to a file and run or manipulated by other
  3190. processes.
  3191. @item
  3192. When a high-level object such as a package or derivation is unquoted
  3193. inside a gexp, the result is as if its output file name had been
  3194. introduced.
  3195. @item
  3196. Gexps carry information about the packages or derivations they refer to,
  3197. and these dependencies are automatically added as inputs to the build
  3198. processes that use them.
  3199. @end itemize
  3200. @cindex lowering, of high-level objects in gexps
  3201. This mechanism is not limited to package and derivation
  3202. objects: @dfn{compilers} able to ``lower'' other high-level objects to
  3203. derivations or files in the store can be defined,
  3204. such that these objects can also be inserted
  3205. into gexps. For example, a useful type of high-level objects that can be
  3206. inserted in a gexp is ``file-like objects'', which make it easy to
  3207. add files to the store and to refer to them in
  3208. derivations and such (see @code{local-file} and @code{plain-file}
  3209. below.)
  3210. To illustrate the idea, here is an example of a gexp:
  3211. @example
  3212. (define build-exp
  3213. #~(begin
  3214. (mkdir #$output)
  3215. (chdir #$output)
  3216. (symlink (string-append #$coreutils "/bin/ls")
  3217. "list-files")))
  3218. @end example
  3219. This gexp can be passed to @code{gexp->derivation}; we obtain a
  3220. derivation that builds a directory containing exactly one symlink to
  3221. @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
  3222. @example
  3223. (gexp->derivation "the-thing" build-exp)
  3224. @end example
  3225. As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
  3226. substituted to the reference to the @var{coreutils} package in the
  3227. actual build code, and @var{coreutils} is automatically made an input to
  3228. the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
  3229. output)}) is replaced by a string containing the directory name of the
  3230. output of the derivation.
  3231. @cindex cross compilation
  3232. In a cross-compilation context, it is useful to distinguish between
  3233. references to the @emph{native} build of a package---that can run on the
  3234. host---versus references to cross builds of a package. To that end, the
  3235. @code{#+} plays the same role as @code{#$}, but is a reference to a
  3236. native package build:
  3237. @example
  3238. (gexp->derivation "vi"
  3239. #~(begin
  3240. (mkdir #$output)
  3241. (system* (string-append #+coreutils "/bin/ln")
  3242. "-s"
  3243. (string-append #$emacs "/bin/emacs")
  3244. (string-append #$output "/bin/vi")))
  3245. #:target "mips64el-linux-gnu")
  3246. @end example
  3247. @noindent
  3248. In the example above, the native build of @var{coreutils} is used, so
  3249. that @command{ln} can actually run on the host; but then the
  3250. cross-compiled build of @var{emacs} is referenced.
  3251. @cindex imported modules, for gexps
  3252. @findex with-imported-modules
  3253. Another gexp feature is @dfn{imported modules}: sometimes you want to be
  3254. able to use certain Guile modules from the ``host environment'' in the
  3255. gexp, so those modules should be imported in the ``build environment''.
  3256. The @code{with-imported-modules} form allows you to express that:
  3257. @example
  3258. (let ((build (with-imported-modules '((guix build utils))
  3259. #~(begin
  3260. (use-modules (guix build utils))
  3261. (mkdir-p (string-append #$output "/bin"))))))
  3262. (gexp->derivation "empty-dir"
  3263. #~(begin
  3264. #$build
  3265. (display "success!\n")
  3266. #t)))
  3267. @end example
  3268. @noindent
  3269. In this example, the @code{(guix build utils)} module is automatically
  3270. pulled into the isolated build environment of our gexp, such that
  3271. @code{(use-modules (guix build utils))} works as expected.
  3272. @cindex module closure
  3273. @findex source-module-closure
  3274. Usually you want the @emph{closure} of the module to be imported---i.e.,
  3275. the module itself and all the modules it depends on---rather than just
  3276. the module; failing to do that, attempts to use the module will fail
  3277. because of missing dependent modules. The @code{source-module-closure}
  3278. procedure computes the closure of a module by looking at its source file
  3279. headers, which comes in handy in this case:
  3280. @example
  3281. (use-modules (guix modules)) ;for 'source-module-closure'
  3282. (with-imported-modules (source-module-closure
  3283. '((guix build utils)
  3284. (gnu build vm)))
  3285. (gexp->derivation "something-with-vms"
  3286. #~(begin
  3287. (use-modules (guix build utils)
  3288. (gnu build vm))
  3289. @dots{})))
  3290. @end example
  3291. The syntactic form to construct gexps is summarized below.
  3292. @deffn {Scheme Syntax} #~@var{exp}
  3293. @deffnx {Scheme Syntax} (gexp @var{exp})
  3294. Return a G-expression containing @var{exp}. @var{exp} may contain one
  3295. or more of the following forms:
  3296. @table @code
  3297. @item #$@var{obj}
  3298. @itemx (ungexp @var{obj})
  3299. Introduce a reference to @var{obj}. @var{obj} may have one of the
  3300. supported types, for example a package or a
  3301. derivation, in which case the @code{ungexp} form is replaced by its
  3302. output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
  3303. If @var{obj} is a list, it is traversed and references to supported
  3304. objects are substituted similarly.
  3305. If @var{obj} is another gexp, its contents are inserted and its
  3306. dependencies are added to those of the containing gexp.
  3307. If @var{obj} is another kind of object, it is inserted as is.
  3308. @item #$@var{obj}:@var{output}
  3309. @itemx (ungexp @var{obj} @var{output})
  3310. This is like the form above, but referring explicitly to the
  3311. @var{output} of @var{obj}---this is useful when @var{obj} produces
  3312. multiple outputs (@pxref{Packages with Multiple Outputs}).
  3313. @item #+@var{obj}
  3314. @itemx #+@var{obj}:output
  3315. @itemx (ungexp-native @var{obj})
  3316. @itemx (ungexp-native @var{obj} @var{output})
  3317. Same as @code{ungexp}, but produces a reference to the @emph{native}
  3318. build of @var{obj} when used in a cross compilation context.
  3319. @item #$output[:@var{output}]
  3320. @itemx (ungexp output [@var{output}])
  3321. Insert a reference to derivation output @var{output}, or to the main
  3322. output when @var{output} is omitted.
  3323. This only makes sense for gexps passed to @code{gexp->derivation}.
  3324. @item #$@@@var{lst}
  3325. @itemx (ungexp-splicing @var{lst})
  3326. Like the above, but splices the contents of @var{lst} inside the
  3327. containing list.
  3328. @item #+@@@var{lst}
  3329. @itemx (ungexp-native-splicing @var{lst})
  3330. Like the above, but refers to native builds of the objects listed in
  3331. @var{lst}.
  3332. @end table
  3333. G-expressions created by @code{gexp} or @code{#~} are run-time objects
  3334. of the @code{gexp?} type (see below.)
  3335. @end deffn
  3336. @deffn {Scheme Syntax} with-imported-modules @var{modules} @var{body}@dots{}
  3337. Mark the gexps defined in @var{body}@dots{} as requiring @var{modules}
  3338. in their execution environment. @var{modules} must be a list of Guile
  3339. module names, such as @code{'((guix build utils) (guix build gremlin))}.
  3340. This form has @emph{lexical} scope: it has an effect on the gexps
  3341. directly defined in @var{body}@dots{}, but not on those defined, say, in
  3342. procedures called from @var{body}@dots{}.
  3343. @end deffn
  3344. @deffn {Scheme Procedure} gexp? @var{obj}
  3345. Return @code{#t} if @var{obj} is a G-expression.
  3346. @end deffn
  3347. G-expressions are meant to be written to disk, either as code building
  3348. some derivation, or as plain files in the store. The monadic procedures
  3349. below allow you to do that (@pxref{The Store Monad}, for more
  3350. information about monads.)
  3351. @deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
  3352. [#:system (%current-system)] [#:target #f] [#:graft? #t] @
  3353. [#:hash #f] [#:hash-algo #f] @
  3354. [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
  3355. [#:module-path @var{%load-path}] @
  3356. [#:references-graphs #f] [#:allowed-references #f] @
  3357. [#:disallowed-references #f] @
  3358. [#:leaked-env-vars #f] @
  3359. [#:script-name (string-append @var{name} "-builder")] @
  3360. [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f]
  3361. Return a derivation @var{name} that runs @var{exp} (a gexp) with
  3362. @var{guile-for-build} (a derivation) on @var{system}; @var{exp} is
  3363. stored in a file called @var{script-name}. When @var{target} is true,
  3364. it is used as the cross-compilation target triplet for packages referred
  3365. to by @var{exp}.
  3366. @var{modules} is deprecated in favor of @code{with-imported-modules}.
  3367. Its meaning is to
  3368. make @var{modules} available in the evaluation context of @var{exp};
  3369. @var{modules} is a list of names of Guile modules searched in
  3370. @var{module-path} to be copied in the store, compiled, and made available in
  3371. the load path during the execution of @var{exp}---e.g., @code{((guix
  3372. build utils) (guix build gnu-build-system))}.
  3373. @var{graft?} determines whether packages referred to by @var{exp} should be grafted when
  3374. applicable.
  3375. When @var{references-graphs} is true, it must be a list of tuples of one of the
  3376. following forms:
  3377. @example
  3378. (@var{file-name} @var{package})
  3379. (@var{file-name} @var{package} @var{output})
  3380. (@var{file-name} @var{derivation})
  3381. (@var{file-name} @var{derivation} @var{output})
  3382. (@var{file-name} @var{store-item})
  3383. @end example
  3384. The right-hand-side of each element of @var{references-graphs} is automatically made
  3385. an input of the build process of @var{exp}. In the build environment, each
  3386. @var{file-name} contains the reference graph of the corresponding item, in a simple
  3387. text format.
  3388. @var{allowed-references} must be either @code{#f} or a list of output names and packages.
  3389. In the latter case, the list denotes store items that the result is allowed to
  3390. refer to. Any reference to another store item will lead to a build error.
  3391. Similarly for @var{disallowed-references}, which can list items that must not be
  3392. referenced by the outputs.
  3393. The other arguments are as for @code{derivation} (@pxref{Derivations}).
  3394. @end deffn
  3395. @cindex file-like objects
  3396. The @code{local-file}, @code{plain-file}, @code{computed-file},
  3397. @code{program-file}, and @code{scheme-file} procedures below return
  3398. @dfn{file-like objects}. That is, when unquoted in a G-expression,
  3399. these objects lead to a file in the store. Consider this G-expression:
  3400. @example
  3401. #~(system* #$(file-append glibc "/sbin/nscd") "-f"
  3402. #$(local-file "/tmp/my-nscd.conf"))
  3403. @end example
  3404. The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it
  3405. to the store. Once expanded, for instance @i{via}
  3406. @code{gexp->derivation}, the G-expression refers to that copy under
  3407. @file{/gnu/store}; thus, modifying or removing the file in @file{/tmp}
  3408. does not have any effect on what the G-expression does.
  3409. @code{plain-file} can be used similarly; it differs in that the file
  3410. content is directly passed as a string.
  3411. @deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
  3412. [#:recursive? #f] [#:select? (const #t)]
  3413. Return an object representing local file @var{file} to add to the store; this
  3414. object can be used in a gexp. If @var{file} is a relative file name, it is looked
  3415. up relative to the source file where this form appears. @var{file} will be added to
  3416. the store under @var{name}--by default the base name of @var{file}.
  3417. When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file}
  3418. designates a flat file and @var{recursive?} is true, its contents are added, and its
  3419. permission bits are kept.
  3420. When @var{recursive?} is true, call @code{(@var{select?} @var{file}
  3421. @var{stat})} for each directory entry, where @var{file} is the entry's
  3422. absolute file name and @var{stat} is the result of @code{lstat}; exclude
  3423. entries for which @var{select?} does not return true.
  3424. This is the declarative counterpart of the @code{interned-file} monadic
  3425. procedure (@pxref{The Store Monad, @code{interned-file}}).
  3426. @end deffn
  3427. @deffn {Scheme Procedure} plain-file @var{name} @var{content}
  3428. Return an object representing a text file called @var{name} with the given
  3429. @var{content} (a string) to be added to the store.
  3430. This is the declarative counterpart of @code{text-file}.
  3431. @end deffn
  3432. @deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @
  3433. [#:options '(#:local-build? #t)]
  3434. Return an object representing the store item @var{name}, a file or
  3435. directory computed by @var{gexp}. @var{options}
  3436. is a list of additional arguments to pass to @code{gexp->derivation}.
  3437. This is the declarative counterpart of @code{gexp->derivation}.
  3438. @end deffn
  3439. @deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
  3440. Return an executable script @var{name} that runs @var{exp} using
  3441. @var{guile}, with @var{exp}'s imported modules in its search path.
  3442. The example below builds a script that simply invokes the @command{ls}
  3443. command:
  3444. @example
  3445. (use-modules (guix gexp) (gnu packages base))
  3446. (gexp->script "list-files"
  3447. #~(execl #$(file-append coreutils "/bin/ls")
  3448. "ls"))
  3449. @end example
  3450. When ``running'' it through the store (@pxref{The Store Monad,
  3451. @code{run-with-store}}), we obtain a derivation that produces an
  3452. executable file @file{/gnu/store/@dots{}-list-files} along these lines:
  3453. @example
  3454. #!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
  3455. !#
  3456. (execl "/gnu/store/@dots{}-coreutils-8.22"/bin/ls" "ls")
  3457. @end example
  3458. @end deffn
  3459. @deffn {Scheme Procedure} program-file @var{name} @var{exp} @
  3460. [#:guile #f]
  3461. Return an object representing the executable store item @var{name} that
  3462. runs @var{gexp}. @var{guile} is the Guile package used to execute that
  3463. script.
  3464. This is the declarative counterpart of @code{gexp->script}.
  3465. @end deffn
  3466. @deffn {Monadic Procedure} gexp->file @var{name} @var{exp} @
  3467. [#:set-load-path? #t]
  3468. Return a derivation that builds a file @var{name} containing @var{exp}.
  3469. When @var{set-load-path?} is true, emit code in the resulting file to
  3470. set @code{%load-path} and @code{%load-compiled-path} to honor
  3471. @var{exp}'s imported modules.
  3472. The resulting file holds references to all the dependencies of @var{exp}
  3473. or a subset thereof.
  3474. @end deffn
  3475. @deffn {Scheme Procedure} scheme-file @var{name} @var{exp}
  3476. Return an object representing the Scheme file @var{name} that contains
  3477. @var{exp}.
  3478. This is the declarative counterpart of @code{gexp->file}.
  3479. @end deffn
  3480. @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
  3481. Return as a monadic value a derivation that builds a text file
  3482. containing all of @var{text}. @var{text} may list, in addition to
  3483. strings, objects of any type that can be used in a gexp: packages,
  3484. derivations, local file objects, etc. The resulting store file holds
  3485. references to all these.
  3486. This variant should be preferred over @code{text-file} anytime the file
  3487. to create will reference items from the store. This is typically the
  3488. case when building a configuration file that embeds store file names,
  3489. like this:
  3490. @example
  3491. (define (profile.sh)
  3492. ;; Return the name of a shell script in the store that
  3493. ;; initializes the 'PATH' environment variable.
  3494. (text-file* "profile.sh"
  3495. "export PATH=" coreutils "/bin:"
  3496. grep "/bin:" sed "/bin\n"))
  3497. @end example
  3498. In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
  3499. will reference @var{coreutils}, @var{grep}, and @var{sed}, thereby
  3500. preventing them from being garbage-collected during its lifetime.
  3501. @end deffn
  3502. @deffn {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{}
  3503. Return an object representing store file @var{name} containing
  3504. @var{text}. @var{text} is a sequence of strings and file-like objects,
  3505. as in:
  3506. @example
  3507. (mixed-text-file "profile"
  3508. "export PATH=" coreutils "/bin:" grep "/bin")
  3509. @end example
  3510. This is the declarative counterpart of @code{text-file*}.
  3511. @end deffn
  3512. @deffn {Scheme Procedure} file-append @var{obj} @var{suffix} @dots{}
  3513. Return a file-like object that expands to the concatenation of @var{obj}
  3514. and @var{suffix}, where @var{obj} is a lowerable object and each
  3515. @var{suffix} is a string.
  3516. As an example, consider this gexp:
  3517. @example
  3518. (gexp->script "run-uname"
  3519. #~(system* #$(file-append coreutils
  3520. "/bin/uname")))
  3521. @end example
  3522. The same effect could be achieved with:
  3523. @example
  3524. (gexp->script "run-uname"
  3525. #~(system* (string-append #$coreutils
  3526. "/bin/uname")))
  3527. @end example
  3528. There is one difference though: in the @code{file-append} case, the
  3529. resulting script contains the absolute file name as a string, whereas in
  3530. the second case, the resulting script contains a @code{(string-append
  3531. @dots{})} expression to construct the file name @emph{at run time}.
  3532. @end deffn
  3533. Of course, in addition to gexps embedded in ``host'' code, there are
  3534. also modules containing build tools. To make it clear that they are
  3535. meant to be used in the build stratum, these modules are kept in the
  3536. @code{(guix build @dots{})} name space.
  3537. @cindex lowering, of high-level objects in gexps
  3538. Internally, high-level objects are @dfn{lowered}, using their compiler,
  3539. to either derivations or store items. For instance, lowering a package
  3540. yields a derivation, and lowering a @code{plain-file} yields a store
  3541. item. This is achieved using the @code{lower-object} monadic pr