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.
 
 
 
 
 
 

10384 lines
394 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. @copying
  10. Copyright @copyright{} 2012, 2013, 2014, 2015, 2016 Ludovic Courtès@*
  11. Copyright @copyright{} 2013, 2014 Andreas Enge@*
  12. Copyright @copyright{} 2013 Nikita Karetnikov@*
  13. Copyright @copyright{} 2015 Mathieu Lirzin@*
  14. Copyright @copyright{} 2014 Pierre-Antoine Rault@*
  15. Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer
  16. Copyright @copyright{} 2015 Leo Famulari
  17. Permission is granted to copy, distribute and/or modify this document
  18. under the terms of the GNU Free Documentation License, Version 1.3 or
  19. any later version published by the Free Software Foundation; with no
  20. Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
  21. copy of the license is included in the section entitled ``GNU Free
  22. Documentation License''.
  23. @end copying
  24. @dircategory Package management
  25. @direntry
  26. * guix: (guix). Guix, the functional package manager.
  27. * guix package: (guix)Invoking guix package
  28. Managing packages with Guix.
  29. * guix build: (guix)Invoking guix build
  30. Building packages with Guix.
  31. * guix system: (guix)Invoking guix system
  32. Managing the operating system configuration.
  33. @end direntry
  34. @dircategory Software development
  35. @direntry
  36. * guix environment: (guix)Invoking guix environment
  37. Building development environments with Guix.
  38. @end direntry
  39. @titlepage
  40. @title GNU Guix Reference Manual
  41. @subtitle Using the GNU Guix Functional Package Manager
  42. @author The GNU Guix Developers
  43. @page
  44. @vskip 0pt plus 1filll
  45. Edition @value{EDITION} @*
  46. @value{UPDATED} @*
  47. @insertcopying
  48. @end titlepage
  49. @contents
  50. @c *********************************************************************
  51. @node Top
  52. @top GNU Guix
  53. This document describes GNU Guix version @value{VERSION}, a functional
  54. package management tool written for the GNU system.
  55. @menu
  56. * Introduction:: What is Guix about?
  57. * Installation:: Installing Guix.
  58. * Package Management:: Package installation, upgrade, etc.
  59. * Emacs Interface:: Using Guix from Emacs.
  60. * Programming Interface:: Using Guix in Scheme.
  61. * Utilities:: Package management commands.
  62. * GNU Distribution:: Software for your friendly GNU system.
  63. * Contributing:: Your help needed!
  64. * Acknowledgments:: Thanks!
  65. * GNU Free Documentation License:: The license of this manual.
  66. * Concept Index:: Concepts.
  67. * Programming Index:: Data types, functions, and variables.
  68. @detailmenu
  69. --- The Detailed Node Listing ---
  70. Installation
  71. * Binary Installation:: Getting Guix running in no time!
  72. * Requirements:: Software needed to build and run Guix.
  73. * Running the Test Suite:: Testing Guix.
  74. * Setting Up the Daemon:: Preparing the build daemon's environment.
  75. * Invoking guix-daemon:: Running the build daemon.
  76. * Application Setup:: Application-specific setup.
  77. Setting Up the Daemon
  78. * Build Environment Setup:: Preparing the isolated build environment.
  79. * Daemon Offload Setup:: Offloading builds to remote machines.
  80. Package Management
  81. * Features:: How Guix will make your life brighter.
  82. * Invoking guix package:: Package installation, removal, etc.
  83. * Substitutes:: Downloading pre-built binaries.
  84. * Packages with Multiple Outputs:: Single source package, multiple outputs.
  85. * Invoking guix gc:: Running the garbage collector.
  86. * Invoking guix pull:: Fetching the latest Guix and distribution.
  87. * Invoking guix archive:: Exporting and importing store files.
  88. Emacs Interface
  89. * Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}.
  90. * Package Management: Emacs Package Management. Managing packages and generations.
  91. * Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands.
  92. * Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names.
  93. * Build Log Mode: Emacs Build Log. Highlighting Guix build logs.
  94. * Completions: Emacs Completions. Completing @command{guix} shell command.
  95. * Development: Emacs Development. Tools for Guix developers.
  96. * Hydra: Emacs Hydra. Interface for Guix build farm.
  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. GNU Distribution
  122. * System Installation:: Installing the whole operating system.
  123. * System Configuration:: Configuring the operating system.
  124. * Installing Debugging Files:: Feeding the debugger.
  125. * Security Updates:: Deploying security fixes quickly.
  126. * Package Modules:: Packages from the programmer's viewpoint.
  127. * Packaging Guidelines:: Growing the distribution.
  128. * Bootstrapping:: GNU/Linux built from scratch.
  129. * Porting:: Targeting another platform or kernel.
  130. System Configuration
  131. * Using the Configuration System:: Customizing your GNU system.
  132. * operating-system Reference:: Detail of operating-system declarations.
  133. * File Systems:: Configuring file system mounts.
  134. * Mapped Devices:: Block device extra processing.
  135. * User Accounts:: Specifying user accounts.
  136. * Locales:: Language and cultural convention settings.
  137. * Services:: Specifying system services.
  138. * Setuid Programs:: Programs running with root privileges.
  139. * X.509 Certificates:: Authenticating HTTPS servers.
  140. * Name Service Switch:: Configuring libc's name service switch.
  141. * Initial RAM Disk:: Linux-Libre bootstrapping.
  142. * GRUB Configuration:: Configuring the boot loader.
  143. * Invoking guix system:: Instantiating a system configuration.
  144. * Defining Services:: Adding new service definitions.
  145. Services
  146. * Base Services:: Essential system services.
  147. * Networking Services:: Network setup, SSH daemon, etc.
  148. * X Window:: Graphical display.
  149. * Desktop Services:: D-Bus and desktop services.
  150. * Database Services:: SQL databases.
  151. * Mail Services:: IMAP, POP3, SMTP, and all that.
  152. * Web Services:: Web servers.
  153. * Various Services:: Other services.
  154. Defining Services
  155. * Service Composition:: The model for composing services.
  156. * Service Types and Services:: Types and services.
  157. * Service Reference:: API reference.
  158. * dmd Services:: A particular type of service.
  159. Packaging Guidelines
  160. * Software Freedom:: What may go into the distribution.
  161. * Package Naming:: What's in a name?
  162. * Version Numbers:: When the name is not enough.
  163. * Synopses and Descriptions:: Helping users find the right package.
  164. * Python Modules:: Taming the snake.
  165. * Perl Modules:: Little pearls.
  166. * Fonts:: Fond of fonts.
  167. Contributing
  168. * Building from Git:: The latest and greatest.
  169. * Running Guix Before It Is Installed:: Hacker tricks.
  170. * The Perfect Setup:: The right tools.
  171. * Coding Style:: Hygiene of the contributor.
  172. * Submitting Patches:: Share your work.
  173. Coding Style
  174. * Programming Paradigm:: How to compose your elements.
  175. * Modules:: Where to store your code?
  176. * Data Types and Pattern Matching:: Implementing data structures.
  177. * Formatting Code:: Writing conventions.
  178. @end detailmenu
  179. @end menu
  180. @c *********************************************************************
  181. @node Introduction
  182. @chapter Introduction
  183. GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
  184. using the international phonetic alphabet (IPA).} is a functional
  185. package management tool for the GNU system. Package management consists
  186. of all activities that relate to building packages from sources,
  187. honoring their build-time and run-time dependencies,
  188. installing packages in user environments, upgrading installed packages
  189. to new versions or rolling back to a previous set, removing unused
  190. software packages, etc.
  191. @cindex functional package management
  192. The term @dfn{functional} refers to a specific package management
  193. discipline pioneered by Nix (@pxref{Acknowledgments}).
  194. In Guix, the package build and installation process is seen
  195. as a function, in the mathematical sense. That function takes inputs,
  196. such as build scripts, a compiler, and libraries, and
  197. returns an installed package. As a pure function, its result depends
  198. solely on its inputs---for instance, it cannot refer to software or
  199. scripts that were not explicitly passed as inputs. A build function
  200. always produces the same result when passed a given set of inputs. It
  201. cannot alter the system's environment in
  202. any way; for instance, it cannot create, modify, or delete files outside
  203. of its build and installation directories. This is achieved by running
  204. build processes in isolated environments (or @dfn{containers}), where only their
  205. explicit inputs are visible.
  206. @cindex store
  207. The result of package build functions is @dfn{cached} in the file
  208. system, in a special directory called @dfn{the store} (@pxref{The
  209. Store}). Each package is installed in a directory of its own, in the
  210. store---by default under @file{/gnu/store}. The directory name contains
  211. a hash of all the inputs used to build that package; thus, changing an
  212. input yields a different directory name.
  213. This approach is the foundation of Guix's salient features: support for
  214. transactional package upgrade and rollback, per-user installation, and
  215. garbage collection of packages (@pxref{Features}).
  216. Guix has a command-line interface, which allows users to build, install,
  217. upgrade, and remove packages, as well as a Scheme programming interface.
  218. @cindex Guix System Distribution
  219. @cindex GuixSD
  220. Last but not least, Guix is used to build a distribution of the GNU
  221. system, with many GNU and non-GNU free software packages. The Guix
  222. System Distribution, or GNU@tie{}GuixSD, takes advantage of the core
  223. properties of Guix at the system level. With GuixSD, users
  224. @emph{declare} all aspects of the operating system configuration, and
  225. Guix takes care of instantiating that configuration in a reproducible,
  226. stateless fashion. @xref{GNU Distribution}.
  227. @c *********************************************************************
  228. @node Installation
  229. @chapter Installation
  230. GNU Guix is available for download from its website at
  231. @url{http://www.gnu.org/software/guix/}. This section describes the
  232. software requirements of Guix, as well as how to install it and get
  233. ready to use it.
  234. Note that this section is concerned with the installation of the package
  235. manager, which can be done on top of a running GNU/Linux system. If,
  236. instead, you want to install the complete GNU operating system,
  237. @pxref{System Installation}.
  238. @menu
  239. * Binary Installation:: Getting Guix running in no time!
  240. * Requirements:: Software needed to build and run Guix.
  241. * Running the Test Suite:: Testing Guix.
  242. * Setting Up the Daemon:: Preparing the build daemon's environment.
  243. * Invoking guix-daemon:: Running the build daemon.
  244. * Application Setup:: Application-specific setup.
  245. @end menu
  246. @node Binary Installation
  247. @section Binary Installation
  248. This section describes how to install Guix on an arbitrary system from a
  249. self-contained tarball providing binaries for Guix and for all its
  250. dependencies. This is often quicker than installing from source, which
  251. is described in the next sections. The only requirement is to have
  252. GNU@tie{}tar and Xz.
  253. Installing goes along these lines:
  254. @enumerate
  255. @item
  256. Download the binary tarball from
  257. @indicateurl{ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz},
  258. where @var{system} is @code{x86_64-linux} for an @code{x86_64} machine
  259. already running the kernel Linux, and so on.
  260. Make sure to download the associated @file{.sig} file and to verify the
  261. authenticity of the tarball against it, along these lines:
  262. @example
  263. $ wget ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
  264. $ gpg --verify guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
  265. @end example
  266. If that command fails because you don't have the required public key,
  267. then run this command to import it:
  268. @example
  269. $ gpg --keyserver keys.gnupg.net --recv-keys 3D9AEBB5
  270. @end example
  271. @noindent
  272. and rerun the @code{gpg --verify} command.
  273. @item
  274. As @code{root}, run:
  275. @example
  276. # cd /tmp
  277. # tar --warning=no-timestamp -xf \
  278. guix-binary-@value{VERSION}.@var{system}.tar.xz
  279. # mv var/guix /var/ && mv gnu /
  280. @end example
  281. This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}.
  282. The latter contains a ready-to-use profile for @code{root} (see next
  283. step.)
  284. Do @emph{not} unpack the tarball on a working Guix system since that
  285. would overwrite its own essential files.
  286. The @code{--warning=no-timestamp} option makes sure GNU@tie{}tar does
  287. not emit warnings about ``implausibly old time stamps'' (such
  288. warnings were triggered by GNU@tie{}tar 1.26 and older; recent
  289. versions are fine.)
  290. They stem from the fact that all the
  291. files in the archive have their modification time set to zero (which
  292. means January 1st, 1970.) This is done on purpose to make sure the
  293. archive content is independent of its creation time, thus making it
  294. reproducible.
  295. @item
  296. Make @code{root}'s profile available under @file{~/.guix-profile}:
  297. @example
  298. # ln -sf /var/guix/profiles/per-user/root/guix-profile \
  299. ~root/.guix-profile
  300. @end example
  301. @item
  302. Create the group and user accounts for build users as explained below
  303. (@pxref{Build Environment Setup}).
  304. @item
  305. Run the daemon:
  306. @example
  307. # ~root/.guix-profile/bin/guix-daemon --build-users-group=guixbuild
  308. @end example
  309. On hosts using the systemd init system, drop
  310. @file{~root/.guix-profile/lib/systemd/system/guix-daemon.service} in
  311. @file{/etc/systemd/system}.
  312. Likewise, on hosts using the Upstart init system, drop
  313. @file{~root/.guix-profile/lib/upstart/system/guix-daemon.conf} in
  314. @file{/etc/init}.
  315. @item
  316. Make the @command{guix} command available to other users on the machine,
  317. for instance with:
  318. @example
  319. # mkdir -p /usr/local/bin
  320. # cd /usr/local/bin
  321. # ln -s /var/guix/profiles/per-user/root/guix-profile/bin/guix
  322. @end example
  323. @item
  324. To use substitutes from @code{hydra.gnu.org} (@pxref{Substitutes}),
  325. authorize them:
  326. @example
  327. # guix archive --authorize < ~root/.guix-profile/share/guix/hydra.gnu.org.pub
  328. @end example
  329. @end enumerate
  330. And that's it! For additional tips and tricks, @pxref{Application
  331. Setup}.
  332. The @code{guix} package must remain available in @code{root}'s
  333. profile, or it would become subject to garbage collection---in which
  334. case you would find yourself badly handicapped by the lack of the
  335. @command{guix} command.
  336. The tarball in question can be (re)produced and verified simply by
  337. running the following command in the Guix source tree:
  338. @example
  339. make guix-binary.@var{system}.tar.xz
  340. @end example
  341. @node Requirements
  342. @section Requirements
  343. This section lists requirements when building Guix from source. The
  344. build procedure for Guix is the same as for other GNU software, and is
  345. not covered here. Please see the files @file{README} and @file{INSTALL}
  346. in the Guix source tree for additional details.
  347. GNU Guix depends on the following packages:
  348. @itemize
  349. @item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.7 or later;
  350. @item @url{http://gnupg.org/, GNU libgcrypt};
  351. @item @url{http://www.gnu.org/software/make/, GNU Make}.
  352. @end itemize
  353. The following dependencies are optional:
  354. @itemize
  355. @item
  356. Installing
  357. @url{http://savannah.nongnu.org/projects/guile-json/, Guile-JSON} will
  358. allow you to use the @command{guix import pypi} command (@pxref{Invoking
  359. guix import}). It is of
  360. interest primarily for developers and not for casual users.
  361. @item
  362. Installing @uref{http://gnutls.org/, GnuTLS-Guile} will
  363. allow you to access @code{https} URLs with the @command{guix download}
  364. command (@pxref{Invoking guix download}), the @command{guix import pypi}
  365. command, and the @command{guix import cpan} command. This is primarily
  366. of interest to developers. @xref{Guile Preparations, how to install the
  367. GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}.
  368. @end itemize
  369. Unless @code{--disable-daemon} was passed to @command{configure}, the
  370. following packages are also needed:
  371. @itemize
  372. @item @url{http://sqlite.org, SQLite 3};
  373. @item @url{http://www.bzip.org, libbz2};
  374. @item @url{http://gcc.gnu.org, GCC's g++}, with support for the
  375. C++11 standard.
  376. @end itemize
  377. When a working installation of @url{http://nixos.org/nix/, the Nix package
  378. manager} is available, you
  379. can instead configure Guix with @code{--disable-daemon}. In that case,
  380. Nix replaces the three dependencies above.
  381. Guix is compatible with Nix, so it is possible to share the same store
  382. between both. To do so, you must pass @command{configure} not only the
  383. same @code{--with-store-dir} value, but also the same
  384. @code{--localstatedir} value. The latter is essential because it
  385. specifies where the database that stores metadata about the store is
  386. located, among other things. The default values for Nix are
  387. @code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
  388. Note that @code{--disable-daemon} is not required if
  389. your goal is to share the store with Nix.
  390. @node Running the Test Suite
  391. @section Running the Test Suite
  392. After a successful @command{configure} and @code{make} run, it is a good
  393. idea to run the test suite. It can help catch issues with the setup or
  394. environment, or bugs in Guix itself---and really, reporting test
  395. failures is a good way to help improve the software. To run the test
  396. suite, type:
  397. @example
  398. make check
  399. @end example
  400. Test cases can run in parallel: you can use the @code{-j} option of
  401. GNU@tie{}make to speed things up. The first run may take a few minutes
  402. on a recent machine; subsequent runs will be faster because the store
  403. that is created for test purposes will already have various things in
  404. cache.
  405. Upon failure, please email @email{bug-guix@@gnu.org} and attach the
  406. @file{test-suite.log} file. When @file{tests/@var{something}.scm}
  407. fails, please also attach the @file{@var{something}.log} file available
  408. in the top-level build directory. Please specify the Guix version being
  409. used as well as version numbers of the dependencies
  410. (@pxref{Requirements}) in your message.
  411. @node Setting Up the Daemon
  412. @section Setting Up the Daemon
  413. @cindex daemon
  414. Operations such as building a package or running the garbage collector
  415. are all performed by a specialized process, the @dfn{build daemon}, on
  416. behalf of clients. Only the daemon may access the store and its
  417. associated database. Thus, any operation that manipulates the store
  418. goes through the daemon. For instance, command-line tools such as
  419. @command{guix package} and @command{guix build} communicate with the
  420. daemon (@i{via} remote procedure calls) to instruct it what to do.
  421. The following sections explain how to prepare the build daemon's
  422. environment. Also @ref{Substitutes}, for information on how to allow
  423. the daemon to download pre-built binaries.
  424. @menu
  425. * Build Environment Setup:: Preparing the isolated build environment.
  426. * Daemon Offload Setup:: Offloading builds to remote machines.
  427. @end menu
  428. @node Build Environment Setup
  429. @subsection Build Environment Setup
  430. In a standard multi-user setup, Guix and its daemon---the
  431. @command{guix-daemon} program---are installed by the system
  432. administrator; @file{/gnu/store} is owned by @code{root} and
  433. @command{guix-daemon} runs as @code{root}. Unprivileged users may use
  434. Guix tools to build packages or otherwise access the store, and the
  435. daemon will do it on their behalf, ensuring that the store is kept in a
  436. consistent state, and allowing built packages to be shared among users.
  437. @cindex build users
  438. When @command{guix-daemon} runs as @code{root}, you may not want package
  439. build processes themselves to run as @code{root} too, for obvious
  440. security reasons. To avoid that, a special pool of @dfn{build users}
  441. should be created for use by build processes started by the daemon.
  442. These build users need not have a shell and a home directory: they will
  443. just be used when the daemon drops @code{root} privileges in build
  444. processes. Having several such users allows the daemon to launch
  445. distinct build processes under separate UIDs, which guarantees that they
  446. do not interfere with each other---an essential feature since builds are
  447. regarded as pure functions (@pxref{Introduction}).
  448. On a GNU/Linux system, a build user pool may be created like this (using
  449. Bash syntax and the @code{shadow} commands):
  450. @c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
  451. @c for why `-G' is needed.
  452. @example
  453. # groupadd --system guixbuild
  454. # for i in `seq -w 1 10`;
  455. do
  456. useradd -g guixbuild -G guixbuild \
  457. -d /var/empty -s `which nologin` \
  458. -c "Guix build user $i" --system \
  459. guixbuilder$i;
  460. done
  461. @end example
  462. @noindent
  463. The number of build users determines how many build jobs may run in
  464. parallel, as specified by the @option{--max-jobs} option
  465. (@pxref{Invoking guix-daemon, @option{--max-jobs}}). The
  466. @code{guix-daemon} program may then be run as @code{root} with the
  467. following command@footnote{If your machine uses the systemd init system,
  468. dropping the @file{@var{prefix}/lib/systemd/system/guix-daemon.service}
  469. file in @file{/etc/systemd/system} will ensure that
  470. @command{guix-daemon} is automatically started. Similarly, if your
  471. machine uses the Upstart init system, drop the
  472. @file{@var{prefix}/lib/upstart/system/guix-daemon.conf}
  473. file in @file{/etc/init}.}:
  474. @example
  475. # guix-daemon --build-users-group=guixbuild
  476. @end example
  477. @cindex chroot
  478. @noindent
  479. This way, the daemon starts build processes in a chroot, under one of
  480. the @code{guixbuilder} users. On GNU/Linux, by default, the chroot
  481. environment contains nothing but:
  482. @c Keep this list in sync with libstore/build.cc! -----------------------
  483. @itemize
  484. @item
  485. a minimal @code{/dev} directory, created mostly independently from the
  486. host @code{/dev}@footnote{``Mostly'', because while the set of files
  487. that appear in the chroot's @code{/dev} is fixed, most of these files
  488. can only be created if the host has them.};
  489. @item
  490. the @code{/proc} directory; it only shows the container's processes
  491. since a separate PID name space is used;
  492. @item
  493. @file{/etc/passwd} with an entry for the current user and an entry for
  494. user @file{nobody};
  495. @item
  496. @file{/etc/group} with an entry for the user's group;
  497. @item
  498. @file{/etc/hosts} with an entry that maps @code{localhost} to
  499. @code{127.0.0.1};
  500. @item
  501. a writable @file{/tmp} directory.
  502. @end itemize
  503. You can influence the directory where the daemon stores build trees
  504. @i{via} the @code{TMPDIR} environment variable. However, the build tree
  505. within the chroot is always @file{/tmp/guix-build-@var{name}.drv-0},
  506. where @var{name} is the derivation name---e.g., @code{coreutils-8.24}.
  507. This way, the value of @code{TMPDIR} does not leak inside build
  508. environments, which avoids discrepancies in cases where build processes
  509. capture the name of their build tree.
  510. If you are installing Guix as an unprivileged user, it is still possible
  511. to run @command{guix-daemon} provided you pass @code{--disable-chroot}.
  512. However, build processes will not be isolated from one another, and not
  513. from the rest of the system. Thus, build processes may interfere with
  514. each other, and may access programs, libraries, and other files
  515. available on the system---making it much harder to view them as
  516. @emph{pure} functions.
  517. @node Daemon Offload Setup
  518. @subsection Using the Offload Facility
  519. @cindex offloading
  520. @cindex build hook
  521. When desired, the build daemon can @dfn{offload}
  522. derivation builds to other machines
  523. running Guix, using the @code{offload} @dfn{build hook}. When that
  524. feature is enabled, a list of user-specified build machines is read from
  525. @file{/etc/guix/machines.scm}; anytime a build is requested, for
  526. instance via @code{guix build}, the daemon attempts to offload it to one
  527. of the machines that satisfies the derivation's constraints, in
  528. particular its system type---e.g., @file{x86_64-linux}. Missing
  529. prerequisites for the build are copied over SSH to the target machine,
  530. which then proceeds with the build; upon success the output(s) of the
  531. build are copied back to the initial machine.
  532. The @file{/etc/guix/machines.scm} file typically looks like this:
  533. @example
  534. (list (build-machine
  535. (name "eightysix.example.org")
  536. (system "x86_64-linux")
  537. (user "bob")
  538. (speed 2.)) ; incredibly fast!
  539. (build-machine
  540. (name "meeps.example.org")
  541. (system "mips64el-linux")
  542. (user "alice")
  543. (private-key
  544. (string-append (getenv "HOME")
  545. "/.lsh/identity-for-guix"))))
  546. @end example
  547. @noindent
  548. In the example above we specify a list of two build machines, one for
  549. the @code{x86_64} architecture and one for the @code{mips64el}
  550. architecture.
  551. In fact, this file is---not surprisingly!---a Scheme file that is
  552. evaluated when the @code{offload} hook is started. Its return value
  553. must be a list of @code{build-machine} objects. While this example
  554. shows a fixed list of build machines, one could imagine, say, using
  555. DNS-SD to return a list of potential build machines discovered in the
  556. local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
  557. Avahi in Guile Scheme Programs}). The @code{build-machine} data type is
  558. detailed below.
  559. @deftp {Data Type} build-machine
  560. This data type represents build machines the daemon may offload builds
  561. to. The important fields are:
  562. @table @code
  563. @item name
  564. The remote machine's host name.
  565. @item system
  566. The remote machine's system type---e.g., @code{"x86_64-linux"}.
  567. @item user
  568. The user account to use when connecting to the remote machine over SSH.
  569. Note that the SSH key pair must @emph{not} be passphrase-protected, to
  570. allow non-interactive logins.
  571. @end table
  572. A number of optional fields may be specified:
  573. @table @code
  574. @item port
  575. Port number of the machine's SSH server (default: 22).
  576. @item private-key
  577. The SSH private key file to use when connecting to the machine.
  578. Currently offloading uses GNU@tie{}lsh as its SSH client
  579. (@pxref{Invoking lsh,,, GNU lsh Manual}). Thus, the key file here must
  580. be an lsh key file. This may change in the future, though.
  581. @item parallel-builds
  582. The number of builds that may run in parallel on the machine (1 by
  583. default.)
  584. @item speed
  585. A ``relative speed factor''. The offload scheduler will tend to prefer
  586. machines with a higher speed factor.
  587. @item features
  588. A list of strings denoting specific features supported by the machine.
  589. An example is @code{"kvm"} for machines that have the KVM Linux modules
  590. and corresponding hardware support. Derivations can request features by
  591. name, and they will be scheduled on matching build machines.
  592. @end table
  593. @end deftp
  594. The @code{guix} command must be in the search path on the build
  595. machines, since offloading works by invoking the @code{guix archive} and
  596. @code{guix build} commands. In addition, the Guix modules must be in
  597. @code{$GUILE_LOAD_PATH} on the build machine---you can check whether
  598. this is the case by running:
  599. @example
  600. lsh build-machine guile -c '(use-modules (guix config))'
  601. @end example
  602. There's one last thing to do once @file{machines.scm} is in place. As
  603. explained above, when offloading, files are transferred back and forth
  604. between the machine stores. For this to work, you first need to
  605. generate a key pair on each machine to allow the daemon to export signed
  606. archives of files from the store (@pxref{Invoking guix archive}):
  607. @example
  608. # guix archive --generate-key
  609. @end example
  610. @noindent
  611. Each build machine must authorize the key of the master machine so that
  612. it accepts store items it receives from the master:
  613. @example
  614. # guix archive --authorize < master-public-key.txt
  615. @end example
  616. @noindent
  617. Likewise, the master machine must authorize the key of each build machine.
  618. All the fuss with keys is here to express pairwise mutual trust
  619. relations between the master and the build machines. Concretely, when
  620. the master receives files from a build machine (and @i{vice versa}), its
  621. build daemon can make sure they are genuine, have not been tampered
  622. with, and that they are signed by an authorized key.
  623. @node Invoking guix-daemon
  624. @section Invoking @command{guix-daemon}
  625. The @command{guix-daemon} program implements all the functionality to
  626. access the store. This includes launching build processes, running the
  627. garbage collector, querying the availability of a build result, etc. It
  628. is normally run as @code{root} like this:
  629. @example
  630. # guix-daemon --build-users-group=guixbuild
  631. @end example
  632. @noindent
  633. For details on how to set it up, @pxref{Setting Up the Daemon}.
  634. @cindex chroot
  635. @cindex container, build environment
  636. @cindex build environment
  637. @cindex reproducible builds
  638. By default, @command{guix-daemon} launches build processes under
  639. different UIDs, taken from the build group specified with
  640. @code{--build-users-group}. In addition, each build process is run in a
  641. chroot environment that only contains the subset of the store that the
  642. build process depends on, as specified by its derivation
  643. (@pxref{Programming Interface, derivation}), plus a set of specific
  644. system directories. By default, the latter contains @file{/dev} and
  645. @file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
  646. @dfn{container}: in addition to having its own file system tree, it has
  647. a separate mount name space, its own PID name space, network name space,
  648. etc. This helps achieve reproducible builds (@pxref{Features}).
  649. When the daemon performs a build on behalf of the user, it creates a
  650. build directory under @file{/tmp} or under the directory specified by
  651. its @code{TMPDIR} environment variable; this directory is shared with
  652. the container for the duration of the build. Be aware that using a
  653. directory other than @file{/tmp} can affect build results---for example,
  654. with a longer directory name, a build process that uses Unix-domain
  655. sockets might hit the name length limitation for @code{sun_path}, which
  656. it would otherwise not hit.
  657. The build directory is automatically deleted upon completion, unless the
  658. build failed and the client specified @option{--keep-failed}
  659. (@pxref{Invoking guix build, @option{--keep-failed}}).
  660. The following command-line options are supported:
  661. @table @code
  662. @item --build-users-group=@var{group}
  663. Take users from @var{group} to run build processes (@pxref{Setting Up
  664. the Daemon, build users}).
  665. @item --no-substitutes
  666. @cindex substitutes
  667. Do not use substitutes for build products. That is, always build things
  668. locally instead of allowing downloads of pre-built binaries
  669. (@pxref{Substitutes}).
  670. By default substitutes are used, unless the client---such as the
  671. @command{guix package} command---is explicitly invoked with
  672. @code{--no-substitutes}.
  673. When the daemon runs with @code{--no-substitutes}, clients can still
  674. explicitly enable substitution @i{via} the @code{set-build-options}
  675. remote procedure call (@pxref{The Store}).
  676. @item --substitute-urls=@var{urls}
  677. @anchor{daemon-substitute-urls}
  678. Consider @var{urls} the default whitespace-separated list of substitute
  679. source URLs. When this option is omitted, @indicateurl{http://hydra.gnu.org}
  680. is used.
  681. This means that substitutes may be downloaded from @var{urls}, as long
  682. as they are signed by a trusted signature (@pxref{Substitutes}).
  683. @cindex build hook
  684. @item --no-build-hook
  685. Do not use the @dfn{build hook}.
  686. The build hook is a helper program that the daemon can start and to
  687. which it submits build requests. This mechanism is used to offload
  688. builds to other machines (@pxref{Daemon Offload Setup}).
  689. @item --cache-failures
  690. Cache build failures. By default, only successful builds are cached.
  691. When this option is used, @command{guix gc --list-failures} can be used
  692. to query the set of store items marked as failed; @command{guix gc
  693. --clear-failures} removes store items from the set of cached failures.
  694. @xref{Invoking guix gc}.
  695. @item --cores=@var{n}
  696. @itemx -c @var{n}
  697. Use @var{n} CPU cores to build each derivation; @code{0} means as many
  698. as available.
  699. The default value is @code{0}, but it may be overridden by clients, such
  700. as the @code{--cores} option of @command{guix build} (@pxref{Invoking
  701. guix build}).
  702. The effect is to define the @code{NIX_BUILD_CORES} environment variable
  703. in the build process, which can then use it to exploit internal
  704. parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
  705. @item --max-jobs=@var{n}
  706. @itemx -M @var{n}
  707. Allow at most @var{n} build jobs in parallel. The default value is
  708. @code{1}. Setting it to @code{0} means that no builds will be performed
  709. locally; instead, the daemon will offload builds (@pxref{Daemon Offload
  710. Setup}), or simply fail.
  711. @item --rounds=@var{N}
  712. Build each derivation @var{n} times in a row, and raise an error if
  713. consecutive build results are not bit-for-bit identical. Note that this
  714. setting can be overridden by clients such as @command{guix build}
  715. (@pxref{Invoking guix build}).
  716. @item --debug
  717. Produce debugging output.
  718. This is useful to debug daemon start-up issues, but then it may be
  719. overridden by clients, for example the @code{--verbosity} option of
  720. @command{guix build} (@pxref{Invoking guix build}).
  721. @item --chroot-directory=@var{dir}
  722. Add @var{dir} to the build chroot.
  723. Doing this may change the result of build processes---for instance if
  724. they use optional dependencies found in @var{dir} when it is available,
  725. and not otherwise. For that reason, it is not recommended to do so.
  726. Instead, make sure that each derivation declares all the inputs that it
  727. needs.
  728. @item --disable-chroot
  729. Disable chroot builds.
  730. Using this option is not recommended since, again, it would allow build
  731. processes to gain access to undeclared dependencies. It is necessary,
  732. though, when @command{guix-daemon} is running under an unprivileged user
  733. account.
  734. @item --disable-log-compression
  735. Disable compression of the build logs.
  736. Unless @code{--lose-logs} is used, all the build logs are kept in the
  737. @var{localstatedir}. To save space, the daemon automatically compresses
  738. them with bzip2 by default. This option disables that.
  739. @item --disable-deduplication
  740. @cindex deduplication
  741. Disable automatic file ``deduplication'' in the store.
  742. By default, files added to the store are automatically ``deduplicated'':
  743. if a newly added file is identical to another one found in the store,
  744. the daemon makes the new file a hard link to the other file. This can
  745. noticeably reduce disk usage, at the expense of slightly increased
  746. input/output load at the end of a build process. This option disables
  747. this optimization.
  748. @item --gc-keep-outputs[=yes|no]
  749. Tell whether the garbage collector (GC) must keep outputs of live
  750. derivations.
  751. When set to ``yes'', the GC will keep the outputs of any live derivation
  752. available in the store---the @code{.drv} files. The default is ``no'',
  753. meaning that derivation outputs are kept only if they are GC roots.
  754. @item --gc-keep-derivations[=yes|no]
  755. Tell whether the garbage collector (GC) must keep derivations
  756. corresponding to live outputs.
  757. When set to ``yes'', as is the case by default, the GC keeps
  758. derivations---i.e., @code{.drv} files---as long as at least one of their
  759. outputs is live. This allows users to keep track of the origins of
  760. items in their store. Setting it to ``no'' saves a bit of disk space.
  761. Note that when both @code{--gc-keep-derivations} and
  762. @code{--gc-keep-outputs} are used, the effect is to keep all the build
  763. prerequisites (the sources, compiler, libraries, and other build-time
  764. tools) of live objects in the store, regardless of whether these
  765. prerequisites are live. This is convenient for developers since it
  766. saves rebuilds or downloads.
  767. @item --impersonate-linux-2.6
  768. On Linux-based systems, impersonate Linux 2.6. This means that the
  769. kernel's @code{uname} system call will report 2.6 as the release number.
  770. This might be helpful to build programs that (usually wrongfully) depend
  771. on the kernel version number.
  772. @item --lose-logs
  773. Do not keep build logs. By default they are kept under
  774. @code{@var{localstatedir}/guix/log}.
  775. @item --system=@var{system}
  776. Assume @var{system} as the current system type. By default it is the
  777. architecture/kernel pair found at configure time, such as
  778. @code{x86_64-linux}.
  779. @item --listen=@var{socket}
  780. Listen for connections on @var{socket}, the file name of a Unix-domain
  781. socket. The default socket is
  782. @file{@var{localstatedir}/daemon-socket/socket}. This option is only
  783. useful in exceptional circumstances, such as if you need to run several
  784. daemons on the same machine.
  785. @end table
  786. @node Application Setup
  787. @section Application Setup
  788. When using Guix on top of GNU/Linux distribution other than GuixSD---a
  789. so-called @dfn{foreign distro}---a few additional steps are needed to
  790. get everything in place. Here are some of them.
  791. @subsection Locales
  792. @anchor{locales-and-locpath}
  793. @cindex locales, when not on GuixSD
  794. @vindex LOCPATH
  795. @vindex GUIX_LOCPATH
  796. Packages installed @i{via} Guix will not use the host system's locale
  797. data. Instead, you must first install one of the locale packages
  798. available with Guix and then define the @code{GUIX_LOCPATH} environment
  799. variable:
  800. @example
  801. $ guix package -i glibc-locales
  802. $ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale
  803. @end example
  804. Note that the @code{glibc-locales} package contains data for all the
  805. locales supported by the GNU@tie{}libc and weighs in at around
  806. 110@tie{}MiB. Alternately, the @code{glibc-utf8-locales} is smaller but
  807. limited to a few UTF-8 locales.
  808. The @code{GUIX_LOCPATH} variable plays a role similar to @code{LOCPATH}
  809. (@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library Reference
  810. Manual}). There are two important differences though:
  811. @enumerate
  812. @item
  813. @code{GUIX_LOCPATH} is honored only by Guix's libc, and not by the libc
  814. provided by foreign distros. Thus, using @code{GUIX_LOCPATH} allows you
  815. to make sure the foreign distro's programs will not end up loading
  816. incompatible locale data.
  817. @item
  818. libc suffixes each entry of @code{GUIX_LOCPATH} with @code{/X.Y}, where
  819. @code{X.Y} is the libc version---e.g., @code{2.22}. This means that,
  820. should your Guix profile contain a mixture of programs linked against
  821. different libc version, each libc version will only try to load locale
  822. data in the right format.
  823. @end enumerate
  824. This is important because the locale data format used by different libc
  825. versions may be incompatible.
  826. @subsection X11 Fonts
  827. The majority of graphical applications use Fontconfig to locate and
  828. load fonts and perform X11-client-side rendering. Guix's
  829. @code{fontconfig} package looks for fonts in @file{$HOME/.guix-profile}
  830. by default. Thus, to allow graphical applications installed with Guix
  831. to display fonts, you will have to install fonts with Guix as well.
  832. Essential font packages include @code{gs-fonts}, @code{font-dejavu}, and
  833. @code{font-gnu-freefont-ttf}.
  834. To display text written in Chinese languages, Japanese, or Korean in
  835. graphical applications, consider installing
  836. @code{font-adobe-source-han-sans} or @code{font-wqy-zenhei}. The former
  837. has multiple outputs, one per language family (@pxref{Packages with
  838. Multiple Outputs}). For instance, the following command installs fonts
  839. for Chinese languages:
  840. @example
  841. guix package -i font-adobe-source-han-sans:cn
  842. @end example
  843. @c TODO What else?
  844. @c *********************************************************************
  845. @node Package Management
  846. @chapter Package Management
  847. The purpose of GNU Guix is to allow users to easily install, upgrade, and
  848. remove software packages, without having to know about their build
  849. procedure or dependencies. Guix also goes beyond this obvious set of
  850. features.
  851. This chapter describes the main features of Guix, as well as the package
  852. management tools it provides. Two user interfaces are provided for
  853. routine package management tasks: A command-line interface described below
  854. (@pxref{Invoking guix package, @code{guix package}}), as well as a visual user
  855. interface in Emacs described in a subsequent chapter (@pxref{Emacs Interface}).
  856. @menu
  857. * Features:: How Guix will make your life brighter.
  858. * Invoking guix package:: Package installation, removal, etc.
  859. * Substitutes:: Downloading pre-built binaries.
  860. * Packages with Multiple Outputs:: Single source package, multiple outputs.
  861. * Invoking guix gc:: Running the garbage collector.
  862. * Invoking guix pull:: Fetching the latest Guix and distribution.
  863. * Invoking guix archive:: Exporting and importing store files.
  864. @end menu
  865. @node Features
  866. @section Features
  867. When using Guix, each package ends up in the @dfn{package store}, in its
  868. own directory---something that resembles
  869. @file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string
  870. (note that Guix comes with an Emacs extension to shorten those file
  871. names, @pxref{Emacs Prettify}.)
  872. Instead of referring to these directories, users have their own
  873. @dfn{profile}, which points to the packages that they actually want to
  874. use. These profiles are stored within each user's home directory, at
  875. @code{$HOME/.guix-profile}.
  876. For example, @code{alice} installs GCC 4.7.2. As a result,
  877. @file{/home/alice/.guix-profile/bin/gcc} points to
  878. @file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
  879. @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
  880. simply continues to point to
  881. @file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
  882. coexist on the same system without any interference.
  883. The @command{guix package} command is the central tool to manage
  884. packages (@pxref{Invoking guix package}). It operates on those per-user
  885. profiles, and can be used @emph{with normal user privileges}.
  886. The command provides the obvious install, remove, and upgrade
  887. operations. Each invocation is actually a @emph{transaction}: either
  888. the specified operation succeeds, or nothing happens. Thus, if the
  889. @command{guix package} process is terminated during the transaction,
  890. or if a power outage occurs during the transaction, then the user's
  891. profile remains in its previous state, and remains usable.
  892. In addition, any package transaction may be @emph{rolled back}. So, if,
  893. for example, an upgrade installs a new version of a package that turns
  894. out to have a serious bug, users may roll back to the previous instance
  895. of their profile, which was known to work well. Similarly, the global
  896. system configuration is subject to transactional upgrades and roll-back
  897. (@pxref{Using the Configuration System}).
  898. All those packages in the package store may be @emph{garbage-collected}.
  899. Guix can determine which packages are still referenced by the user
  900. profiles, and remove those that are provably no longer referenced
  901. (@pxref{Invoking guix gc}). Users may also explicitly remove old
  902. generations of their profile so that the packages they refer to can be
  903. collected.
  904. @cindex reproducibility
  905. @cindex reproducible builds
  906. Finally, Guix takes a @dfn{purely functional} approach to package
  907. management, as described in the introduction (@pxref{Introduction}).
  908. Each @file{/gnu/store} package directory name contains a hash of all the
  909. inputs that were used to build that package---compiler, libraries, build
  910. scripts, etc. This direct correspondence allows users to make sure a
  911. given package installation matches the current state of their
  912. distribution. It also helps maximize @dfn{build reproducibility}:
  913. thanks to the isolated build environments that are used, a given build
  914. is likely to yield bit-identical files when performed on different
  915. machines (@pxref{Invoking guix-daemon, container}).
  916. @cindex substitutes
  917. This foundation allows Guix to support @dfn{transparent binary/source
  918. deployment}. When a pre-built binary for a @file{/gnu/store} item is
  919. available from an external source---a @dfn{substitute}, Guix just
  920. downloads it and unpacks it;
  921. otherwise, it builds the package from source, locally
  922. (@pxref{Substitutes}).
  923. Control over the build environment is a feature that is also useful for
  924. developers. The @command{guix environment} command allows developers of
  925. a package to quickly set up the right development environment for their
  926. package, without having to manually install the package's dependencies
  927. in their profile (@pxref{Invoking guix environment}).
  928. @node Invoking guix package
  929. @section Invoking @command{guix package}
  930. The @command{guix package} command is the tool that allows users to
  931. install, upgrade, and remove packages, as well as rolling back to
  932. previous configurations. It operates only on the user's own profile,
  933. and works with normal user privileges (@pxref{Features}). Its syntax
  934. is:
  935. @example
  936. guix package @var{options}
  937. @end example
  938. Primarily, @var{options} specifies the operations to be performed during
  939. the transaction. Upon completion, a new profile is created, but
  940. previous @dfn{generations} of the profile remain available, should the user
  941. want to roll back.
  942. For example, to remove @code{lua} and install @code{guile} and
  943. @code{guile-cairo} in a single transaction:
  944. @example
  945. guix package -r lua -i guile guile-cairo
  946. @end example
  947. @command{guix package} also supports a @dfn{declarative approach}
  948. whereby the user specifies the exact set of packages to be available and
  949. passes it @i{via} the @option{--manifest} option
  950. (@pxref{profile-manifest, @option{--manifest}}).
  951. For each user, a symlink to the user's default profile is automatically
  952. created in @file{$HOME/.guix-profile}. This symlink always points to the
  953. current generation of the user's default profile. Thus, users can add
  954. @file{$HOME/.guix-profile/bin} to their @code{PATH} environment
  955. variable, and so on.
  956. @cindex search paths
  957. If you are not using the Guix System Distribution, consider adding the
  958. following lines to your @file{~/.bash_profile} (@pxref{Bash Startup
  959. Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned
  960. shells get all the right environment variable definitions:
  961. @example
  962. GUIX_PROFILE="$HOME/.guix-profile" \
  963. source "$HOME/.guix-profile/etc/profile"
  964. @end example
  965. In a multi-user setup, user profiles are stored in a place registered as
  966. a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
  967. to (@pxref{Invoking guix gc}). That directory is normally
  968. @code{@var{localstatedir}/profiles/per-user/@var{user}}, where
  969. @var{localstatedir} is the value passed to @code{configure} as
  970. @code{--localstatedir}, and @var{user} is the user name. The
  971. @file{per-user} directory is created when @command{guix-daemon} is
  972. started, and the @var{user} sub-directory is created by @command{guix
  973. package}.
  974. The @var{options} can be among the following:
  975. @table @code
  976. @item --install=@var{package} @dots{}
  977. @itemx -i @var{package} @dots{}
  978. Install the specified @var{package}s.
  979. Each @var{package} may specify either a simple package name, such as
  980. @code{guile}, or a package name followed by a hyphen and version number,
  981. such as @code{guile-1.8.8} or simply @code{guile-1.8} (in the latter
  982. case, the newest version prefixed by @code{1.8} is selected.)
  983. If no version number is specified, the
  984. newest available version will be selected. In addition, @var{package}
  985. may contain a colon, followed by the name of one of the outputs of the
  986. package, as in @code{gcc:doc} or @code{binutils-2.22:lib}
  987. (@pxref{Packages with Multiple Outputs}). Packages with a corresponding
  988. name (and optionally version) are searched for among the GNU
  989. distribution modules (@pxref{Package Modules}).
  990. @cindex propagated inputs
  991. Sometimes packages have @dfn{propagated inputs}: these are dependencies
  992. that automatically get installed along with the required package
  993. (@pxref{package-propagated-inputs, @code{propagated-inputs} in
  994. @code{package} objects}, for information about propagated inputs in
  995. package definitions).
  996. @anchor{package-cmd-propagated-inputs}
  997. An example is the GNU MPC library: its C header files refer to those of
  998. the GNU MPFR library, which in turn refer to those of the GMP library.
  999. Thus, when installing MPC, the MPFR and GMP libraries also get installed
  1000. in the profile; removing MPC also removes MPFR and GMP---unless they had
  1001. also been explicitly installed independently.
  1002. Besides, packages sometimes rely on the definition of environment
  1003. variables for their search paths (see explanation of
  1004. @code{--search-paths} below). Any missing or possibly incorrect
  1005. environment variable definitions are reported here.
  1006. @c XXX: keep me up-to-date
  1007. Finally, when installing a GNU package, the tool reports the
  1008. availability of a newer upstream version. In the future, it may provide
  1009. the option of installing directly from the upstream version, even if
  1010. that version is not yet in the distribution.
  1011. @item --install-from-expression=@var{exp}
  1012. @itemx -e @var{exp}
  1013. Install the package @var{exp} evaluates to.
  1014. @var{exp} must be a Scheme expression that evaluates to a
  1015. @code{<package>} object. This option is notably useful to disambiguate
  1016. between same-named variants of a package, with expressions such as
  1017. @code{(@@ (gnu packages base) guile-final)}.
  1018. Note that this option installs the first output of the specified
  1019. package, which may be insufficient when needing a specific output of a
  1020. multiple-output package.
  1021. @item --install-from-file=@var{file}
  1022. @itemx -f @var{file}
  1023. Install the package that the code within @var{file} evaluates to.
  1024. As an example, @var{file} might contain a definition like this
  1025. (@pxref{Defining Packages}):
  1026. @example
  1027. @verbatiminclude package-hello.scm
  1028. @end example
  1029. Developers may find it useful to include such a @file{package.scm} file
  1030. in the root of their project's source tree that can be used to test
  1031. development snapshots and create reproducible development environments
  1032. (@pxref{Invoking guix environment}).
  1033. @item --remove=@var{package} @dots{}
  1034. @itemx -r @var{package} @dots{}
  1035. Remove the specified @var{package}s.
  1036. As for @code{--install}, each @var{package} may specify a version number
  1037. and/or output name in addition to the package name. For instance,
  1038. @code{-r glibc:debug} would remove the @code{debug} output of
  1039. @code{glibc}.
  1040. @item --upgrade[=@var{regexp} @dots{}]
  1041. @itemx -u [@var{regexp} @dots{}]
  1042. Upgrade all the installed packages. If one or more @var{regexp}s are
  1043. specified, upgrade only installed packages whose name matches a
  1044. @var{regexp}. Also see the @code{--do-not-upgrade} option below.
  1045. Note that this upgrades package to the latest version of packages found
  1046. in the distribution currently installed. To update your distribution,
  1047. you should regularly run @command{guix pull} (@pxref{Invoking guix
  1048. pull}).
  1049. @item --do-not-upgrade[=@var{regexp} @dots{}]
  1050. When used together with the @code{--upgrade} option, do @emph{not}
  1051. upgrade any packages whose name matches a @var{regexp}. For example, to
  1052. upgrade all packages in the current profile except those containing the
  1053. substring ``emacs'':
  1054. @example
  1055. $ guix package --upgrade . --do-not-upgrade emacs
  1056. @end example
  1057. @item @anchor{profile-manifest}--manifest=@var{file}
  1058. @itemx -m @var{file}
  1059. @cindex profile declaration
  1060. @cindex profile manifest
  1061. Create a new generation of the profile from the manifest object
  1062. returned by the Scheme code in @var{file}.
  1063. This allows you to @emph{declare} the profile's contents rather than
  1064. constructing it through a sequence of @code{--install} and similar
  1065. commands. The advantage is that @var{file} can be put under version
  1066. control, copied to different machines to reproduce the same profile, and
  1067. so on.
  1068. @c FIXME: Add reference to (guix profile) documentation when available.
  1069. @var{file} must return a @dfn{manifest} object, which is roughly a list
  1070. of packages:
  1071. @findex packages->manifest
  1072. @example
  1073. (use-package-modules guile emacs)
  1074. (packages->manifest
  1075. (list emacs
  1076. guile-2.0
  1077. ;; Use a specific package output.
  1078. (list guile-2.0 "debug")))
  1079. @end example
  1080. @item --roll-back
  1081. Roll back to the previous @dfn{generation} of the profile---i.e., undo
  1082. the last transaction.
  1083. When combined with options such as @code{--install}, roll back occurs
  1084. before any other actions.
  1085. When rolling back from the first generation that actually contains
  1086. installed packages, the profile is made to point to the @dfn{zeroth
  1087. generation}, which contains no files apart from its own meta-data.
  1088. Installing, removing, or upgrading packages from a generation that has
  1089. been rolled back to overwrites previous future generations. Thus, the
  1090. history of a profile's generations is always linear.
  1091. @item --switch-generation=@var{pattern}
  1092. @itemx -S @var{pattern}
  1093. Switch to a particular generation defined by @var{pattern}.
  1094. @var{pattern} may be either a generation number or a number prefixed
  1095. with ``+'' or ``-''. The latter means: move forward/backward by a
  1096. specified number of generations. For example, if you want to return to
  1097. the latest generation after @code{--roll-back}, use
  1098. @code{--switch-generation=+1}.
  1099. The difference between @code{--roll-back} and
  1100. @code{--switch-generation=-1} is that @code{--switch-generation} will
  1101. not make a zeroth generation, so if a specified generation does not
  1102. exist, the current generation will not be changed.
  1103. @item --search-paths[=@var{kind}]
  1104. @cindex search paths
  1105. Report environment variable definitions, in Bash syntax, that may be
  1106. needed in order to use the set of installed packages. These environment
  1107. variables are used to specify @dfn{search paths} for files used by some
  1108. of the installed packages.
  1109. For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
  1110. environment variables to be defined so it can look for headers and
  1111. libraries in the user's profile (@pxref{Environment Variables,,, gcc,
  1112. Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
  1113. library are installed in the profile, then @code{--search-paths} will
  1114. suggest setting these variables to @code{@var{profile}/include} and
  1115. @code{@var{profile}/lib}, respectively.
  1116. The typical use case is to define these environment variables in the
  1117. shell:
  1118. @example
  1119. $ eval `guix package --search-paths`
  1120. @end example
  1121. @var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix},
  1122. meaning that the returned environment variable definitions will either
  1123. be exact settings, or prefixes or suffixes of the current value of these
  1124. variables. When omitted, @var{kind} defaults to @code{exact}.
  1125. This option can also be used to compute the @emph{combined} search paths
  1126. of several profiles. Consider this example:
  1127. @example
  1128. $ guix package -p foo -i guile
  1129. $ guix package -p bar -i guile-json
  1130. $ guix package -p foo -p bar --search-paths
  1131. @end example
  1132. The last command above reports about the @code{GUILE_LOAD_PATH}
  1133. variable, even though, taken individually, neither @file{foo} nor
  1134. @file{bar} would lead to that recommendation.
  1135. @item --profile=@var{profile}
  1136. @itemx -p @var{profile}
  1137. Use @var{profile} instead of the user's default profile.
  1138. @item --verbose
  1139. Produce verbose output. In particular, emit the environment's build log
  1140. on the standard error port.
  1141. @item --bootstrap
  1142. Use the bootstrap Guile to build the profile. This option is only
  1143. useful to distribution developers.
  1144. @end table
  1145. In addition to these actions @command{guix package} supports the
  1146. following options to query the current state of a profile, or the
  1147. availability of packages:
  1148. @table @option
  1149. @item --search=@var{regexp}
  1150. @itemx -s @var{regexp}
  1151. @cindex searching for packages
  1152. List the available packages whose name, synopsis, or description matches
  1153. @var{regexp}. Print all the meta-data of matching packages in
  1154. @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
  1155. GNU recutils manual}).
  1156. This allows specific fields to be extracted using the @command{recsel}
  1157. command, for instance:
  1158. @example
  1159. $ guix package -s malloc | recsel -p name,version
  1160. name: glibc
  1161. version: 2.17
  1162. name: libgc
  1163. version: 7.2alpha6
  1164. @end example
  1165. Similarly, to show the name of all the packages available under the
  1166. terms of the GNU@tie{}LGPL version 3:
  1167. @example
  1168. $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
  1169. name: elfutils
  1170. name: gmp
  1171. @dots{}
  1172. @end example
  1173. It is also possible to refine search results using several @code{-s}
  1174. flags. For example, the following command returns a list of board
  1175. games:
  1176. @example
  1177. $ guix package -s '\<board\>' -s game | recsel -p name
  1178. name: gnubg
  1179. @dots{}
  1180. @end example
  1181. If we were to omit @code{-s game}, we would also get software packages
  1182. that deal with printed circuit boards; removing the angle brackets
  1183. around @code{board} would further add packages that have to do with
  1184. keyboards.
  1185. And now for a more elaborate example. The following command searches
  1186. for cryptographic libraries, filters out Haskell, Perl, Python, and Ruby
  1187. libraries, and prints the name and synopsis of the matching packages:
  1188. @example
  1189. $ guix package -s crypto -s library | \
  1190. recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
  1191. @end example
  1192. @noindent
  1193. @xref{Selection Expressions,,, recutils, GNU recutils manual}, for more
  1194. information on @dfn{selection expressions} for @code{recsel -e}.
  1195. @item --show=@var{package}
  1196. Show details about @var{package}, taken from the list of available packages, in
  1197. @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
  1198. recutils manual}).
  1199. @example
  1200. $ guix package --show=python | recsel -p name,version
  1201. name: python
  1202. version: 2.7.6
  1203. name: python
  1204. version: 3.3.5
  1205. @end example
  1206. You may also specify the full name of a package to only get details about a
  1207. specific version of it:
  1208. @example
  1209. $ guix package --show=python-3.3.5 | recsel -p name,version
  1210. name: python
  1211. version: 3.3.5
  1212. @end example
  1213. @item --list-installed[=@var{regexp}]
  1214. @itemx -I [@var{regexp}]
  1215. List the currently installed packages in the specified profile, with the
  1216. most recently installed packages shown last. When @var{regexp} is
  1217. specified, list only installed packages whose name matches @var{regexp}.
  1218. For each installed package, print the following items, separated by
  1219. tabs: the package name, its version string, the part of the package that
  1220. is installed (for instance, @code{out} for the default output,
  1221. @code{include} for its headers, etc.), and the path of this package in
  1222. the store.
  1223. @item --list-available[=@var{regexp}]
  1224. @itemx -A [@var{regexp}]
  1225. List packages currently available in the distribution for this system
  1226. (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
  1227. installed packages whose name matches @var{regexp}.
  1228. For each package, print the following items separated by tabs: its name,
  1229. its version string, the parts of the package (@pxref{Packages with
  1230. Multiple Outputs}), and the source location of its definition.
  1231. @item --list-generations[=@var{pattern}]
  1232. @itemx -l [@var{pattern}]
  1233. Return a list of generations along with their creation dates; for each
  1234. generation, show the installed packages, with the most recently
  1235. installed packages shown last. Note that the zeroth generation is never
  1236. shown.
  1237. For each installed package, print the following items, separated by
  1238. tabs: the name of a package, its version string, the part of the package
  1239. that is installed (@pxref{Packages with Multiple Outputs}), and the
  1240. location of this package in the store.
  1241. When @var{pattern} is used, the command returns only matching
  1242. generations. Valid patterns include:
  1243. @itemize
  1244. @item @emph{Integers and comma-separated integers}. Both patterns denote
  1245. generation numbers. For instance, @code{--list-generations=1} returns
  1246. the first one.
  1247. And @code{--list-generations=1,8,2} outputs three generations in the
  1248. specified order. Neither spaces nor trailing commas are allowed.
  1249. @item @emph{Ranges}. @code{--list-generations=2..9} prints the
  1250. specified generations and everything in between. Note that the start of
  1251. a range must be lesser than its end.
  1252. It is also possible to omit the endpoint. For example,
  1253. @code{--list-generations=2..}, returns all generations starting from the
  1254. second one.
  1255. @item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
  1256. or months by passing an integer along with the first letter of the
  1257. duration. For example, @code{--list-generations=20d} lists generations
  1258. that are up to 20 days old.
  1259. @end itemize
  1260. @item --delete-generations[=@var{pattern}]
  1261. @itemx -d [@var{pattern}]
  1262. When @var{pattern} is omitted, delete all generations except the current
  1263. one.
  1264. This command accepts the same patterns as @option{--list-generations}.
  1265. When @var{pattern} is specified, delete the matching generations. When
  1266. @var{pattern} specifies a duration, generations @emph{older} than the
  1267. specified duration match. For instance, @code{--delete-generations=1m}
  1268. deletes generations that are more than one month old.
  1269. If the current generation matches, it is @emph{not} deleted. Also, the
  1270. zeroth generation is never deleted.
  1271. Note that deleting generations prevents roll-back to them.
  1272. Consequently, this command must be used with care.
  1273. @end table
  1274. Finally, since @command{guix package} may actually start build
  1275. processes, it supports all the common build options that @command{guix
  1276. build} supports (@pxref{Invoking guix build, common build options}).
  1277. @node Substitutes
  1278. @section Substitutes
  1279. @cindex substitutes
  1280. @cindex pre-built binaries
  1281. Guix supports transparent source/binary deployment, which means that it
  1282. can either build things locally, or download pre-built items from a
  1283. server. We call these pre-built items @dfn{substitutes}---they are
  1284. substitutes for local build results. In many cases, downloading a
  1285. substitute is much faster than building things locally.
  1286. Substitutes can be anything resulting from a derivation build
  1287. (@pxref{Derivations}). Of course, in the common case, they are
  1288. pre-built package binaries, but source tarballs, for instance, which
  1289. also result from derivation builds, can be available as substitutes.
  1290. The @code{hydra.gnu.org} server is a front-end to a build farm that
  1291. builds packages from the GNU distribution continuously for some
  1292. architectures, and makes them available as substitutes (@pxref{Emacs
  1293. Hydra}, for information on how to query the continuous integration
  1294. server). This is the
  1295. default source of substitutes; it can be overridden by passing the
  1296. @option{--substitute-urls} option either to @command{guix-daemon}
  1297. (@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
  1298. or to client tools such as @command{guix package}
  1299. (@pxref{client-substitute-urls,, client @option{--substitute-urls}
  1300. option}).
  1301. @cindex security
  1302. @cindex digital signatures
  1303. To allow Guix to download substitutes from @code{hydra.gnu.org}, you
  1304. must add its public key to the access control list (ACL) of archive
  1305. imports, using the @command{guix archive} command (@pxref{Invoking guix
  1306. archive}). Doing so implies that you trust @code{hydra.gnu.org} to not
  1307. be compromised and to serve genuine substitutes.
  1308. This public key is installed along with Guix, in
  1309. @code{@var{prefix}/share/guix/hydra.gnu.org.pub}, where @var{prefix} is
  1310. the installation prefix of Guix. If you installed Guix from source,
  1311. make sure you checked the GPG signature of
  1312. @file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
  1313. Then, you can run something like this:
  1314. @example
  1315. # guix archive --authorize < hydra.gnu.org.pub
  1316. @end example
  1317. Once this is in place, the output of a command like @code{guix build}
  1318. should change from something like:
  1319. @example
  1320. $ guix build emacs --dry-run
  1321. The following derivations would be built:
  1322. /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
  1323. /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
  1324. /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
  1325. /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
  1326. @dots{}
  1327. @end example
  1328. @noindent
  1329. to something like:
  1330. @example
  1331. $ guix build emacs --dry-run
  1332. The following files would be downloaded:
  1333. /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
  1334. /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
  1335. /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
  1336. /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
  1337. @dots{}
  1338. @end example
  1339. @noindent
  1340. This indicates that substitutes from @code{hydra.gnu.org} are usable and
  1341. will be downloaded, when possible, for future builds.
  1342. Guix ignores substitutes that are not signed, or that are not signed by
  1343. one of the keys listed in the ACL. It also detects and raises an error
  1344. when attempting to use a substitute that has been tampered with.
  1345. The substitute mechanism can be disabled globally by running
  1346. @code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
  1347. guix-daemon}). It can also be disabled temporarily by passing the
  1348. @code{--no-substitutes} option to @command{guix package}, @command{guix
  1349. build}, and other command-line tools.
  1350. Today, each individual's control over their own computing is at the
  1351. mercy of institutions, corporations, and groups with enough power and
  1352. determination to subvert the computing infrastructure and exploit its
  1353. weaknesses. While using @code{hydra.gnu.org} substitutes can be
  1354. convenient, we encourage users to also build on their own, or even run
  1355. their own build farm, such that @code{hydra.gnu.org} is less of an
  1356. interesting target. One way to help is by publishing the software you
  1357. build using @command{guix publish} so that others have one more choice
  1358. of server to download substitutes from (@pxref{Invoking guix publish}).
  1359. Guix has the foundations to maximize build reproducibility
  1360. (@pxref{Features}). In most cases, independent builds of a given
  1361. package or derivation should yield bit-identical results. Thus, through
  1362. a diverse set of independent package builds, we can strengthen the
  1363. integrity of our systems. The @command{guix challenge} command aims to
  1364. help users assess substitute servers, and to assist developers in
  1365. finding out about non-deterministic package builds (@pxref{Invoking guix
  1366. challenge}). Similarly, the @option{--check} option of @command{guix
  1367. build} allows users to check whether previously-installed substitutes
  1368. are genuine by rebuilding them locally (@pxref{build-check,
  1369. @command{guix build --check}}).
  1370. In the future, we want Guix to have support to publish and retrieve
  1371. binaries to/from other users, in a peer-to-peer fashion. If you would
  1372. like to discuss this project, join us on @email{guix-devel@@gnu.org}.
  1373. @node Packages with Multiple Outputs
  1374. @section Packages with Multiple Outputs
  1375. @cindex multiple-output packages
  1376. @cindex package outputs
  1377. Often, packages defined in Guix have a single @dfn{output}---i.e., the
  1378. source package leads exactly one directory in the store. When running
  1379. @command{guix package -i glibc}, one installs the default output of the
  1380. GNU libc package; the default output is called @code{out}, but its name
  1381. can be omitted as shown in this command. In this particular case, the
  1382. default output of @code{glibc} contains all the C header files, shared
  1383. libraries, static libraries, Info documentation, and other supporting
  1384. files.
  1385. Sometimes it is more appropriate to separate the various types of files
  1386. produced from a single source package into separate outputs. For
  1387. instance, the GLib C library (used by GTK+ and related packages)
  1388. installs more than 20 MiB of reference documentation as HTML pages.
  1389. To save space for users who do not need it, the documentation goes to a
  1390. separate output, called @code{doc}. To install the main GLib output,
  1391. which contains everything but the documentation, one would run:
  1392. @example
  1393. guix package -i glib
  1394. @end example
  1395. The command to install its documentation is:
  1396. @example
  1397. guix package -i glib:doc
  1398. @end example
  1399. Some packages install programs with different ``dependency footprints''.
  1400. For instance, the WordNet package install both command-line tools and
  1401. graphical user interfaces (GUIs). The former depend solely on the C
  1402. library, whereas the latter depend on Tcl/Tk and the underlying X
  1403. libraries. In this case, we leave the command-line tools in the default
  1404. output, whereas the GUIs are in a separate output. This allows users
  1405. who do not need the GUIs to save space. The @command{guix size} command
  1406. can help find out about such situations (@pxref{Invoking guix size}).
  1407. @command{guix graph} can also be helpful (@pxref{Invoking guix graph}).
  1408. There are several such multiple-output packages in the GNU distribution.
  1409. Other conventional output names include @code{lib} for libraries and
  1410. possibly header files, @code{bin} for stand-alone programs, and
  1411. @code{debug} for debugging information (@pxref{Installing Debugging
  1412. Files}). The outputs of a packages are listed in the third column of
  1413. the output of @command{guix package --list-available} (@pxref{Invoking
  1414. guix package}).
  1415. @node Invoking guix gc
  1416. @section Invoking @command{guix gc}
  1417. @cindex garbage collector
  1418. Packages that are installed but not used may be @dfn{garbage-collected}.
  1419. The @command{guix gc} command allows users to explicitly run the garbage
  1420. collector to reclaim space from the @file{/gnu/store} directory. It is
  1421. the @emph{only} way to remove files from @file{/gnu/store}---removing
  1422. files or directories manually may break it beyond repair!
  1423. The garbage collector has a set of known @dfn{roots}: any file under
  1424. @file{/gnu/store} reachable from a root is considered @dfn{live} and
  1425. cannot be deleted; any other file is considered @dfn{dead} and may be
  1426. deleted. The set of garbage collector roots includes default user
  1427. profiles, and may be augmented with @command{guix build --root}, for
  1428. example (@pxref{Invoking guix build}).
  1429. Prior to running @code{guix gc --collect-garbage} to make space, it is
  1430. often useful to remove old generations from user profiles; that way, old
  1431. package builds referenced by those generations can be reclaimed. This
  1432. is achieved by running @code{guix package --delete-generations}
  1433. (@pxref{Invoking guix package}).
  1434. The @command{guix gc} command has three modes of operation: it can be
  1435. used to garbage-collect any dead files (the default), to delete specific
  1436. files (the @code{--delete} option), to print garbage-collector
  1437. information, or for more advanced queries. The garbage collection
  1438. options are as follows:
  1439. @table @code
  1440. @item --collect-garbage[=@var{min}]
  1441. @itemx -C [@var{min}]
  1442. Collect garbage---i.e., unreachable @file{/gnu/store} files and
  1443. sub-directories. This is the default operation when no option is
  1444. specified.
  1445. When @var{min} is given, stop once @var{min} bytes have been collected.
  1446. @var{min} may be a number of bytes, or it may include a unit as a
  1447. suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
  1448. (@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
  1449. When @var{min} is omitted, collect all the garbage.
  1450. @item --delete
  1451. @itemx -d
  1452. Attempt to delete all the store files and directories specified as
  1453. arguments. This fails if some of the files are not in the store, or if
  1454. they are still live.
  1455. @item --list-failures
  1456. List store items corresponding to cached build failures.
  1457. This prints nothing unless the daemon was started with
  1458. @option{--cache-failures} (@pxref{Invoking guix-daemon,
  1459. @option{--cache-failures}}).
  1460. @item --clear-failures
  1461. Remove the specified store items from the failed-build cache.
  1462. Again, this option only makes sense when the daemon is started with
  1463. @option{--cache-failures}. Otherwise, it does nothing.
  1464. @item --list-dead
  1465. Show the list of dead files and directories still present in the
  1466. store---i.e., files and directories no longer reachable from any root.
  1467. @item --list-live
  1468. Show the list of live store files and directories.
  1469. @end table
  1470. In addition, the references among existing store files can be queried:
  1471. @table @code
  1472. @item --references
  1473. @itemx --referrers
  1474. List the references (respectively, the referrers) of store files given
  1475. as arguments.
  1476. @item --requisites
  1477. @itemx -R
  1478. @cindex closure
  1479. List the requisites of the store files passed as arguments. Requisites
  1480. include the store files themselves, their references, and the references
  1481. of these, recursively. In other words, the returned list is the
  1482. @dfn{transitive closure} of the store files.
  1483. @xref{Invoking guix size}, for a tool to profile the size of an
  1484. element's closure. @xref{Invoking guix graph}, for a tool to visualize
  1485. the graph of references.
  1486. @end table
  1487. Lastly, the following options allow you to check the integrity of the
  1488. store and to control disk usage.
  1489. @table @option
  1490. @item --verify[=@var{options}]
  1491. @cindex integrity, of the store
  1492. @cindex integrity checking
  1493. Verify the integrity of the store.
  1494. By default, make sure that all the store items marked as valid in the
  1495. daemon's database actually exist in @file{/gnu/store}.
  1496. When provided, @var{options} must a comma-separated list containing one
  1497. or more of @code{contents} and @code{repair}.
  1498. When passing @option{--verify=contents}, the daemon will compute the
  1499. content hash of each store item and compare it against its hash in the
  1500. database. Hash mismatches are reported as data corruptions. Because it
  1501. traverses @emph{all the files in the store}, this command can take a
  1502. long time, especially on systems with a slow disk drive.
  1503. @cindex repairing the store
  1504. Using @option{--verify=repair} or @option{--verify=contents,repair}
  1505. causes the daemon to try to repair corrupt store items by fetching
  1506. substitutes for them (@pxref{Substitutes}). Because repairing is not
  1507. atomic, and thus potentially dangerous, it is available only to the
  1508. system administrator.
  1509. @item --optimize
  1510. @cindex deduplication
  1511. Optimize the store by hard-linking identical files---this is
  1512. @dfn{deduplication}.
  1513. The daemon performs deduplication after each successful build or archive
  1514. import, unless it was started with @code{--disable-deduplication}
  1515. (@pxref{Invoking guix-daemon, @code{--disable-deduplication}}). Thus,
  1516. this option is primarily useful when the daemon was running with
  1517. @code{--disable-deduplication}.
  1518. @end table
  1519. @node Invoking guix pull
  1520. @section Invoking @command{guix pull}
  1521. Packages are installed or upgraded to the latest version available in
  1522. the distribution currently available on your local machine. To update
  1523. that distribution, along with the Guix tools, you must run @command{guix
  1524. pull}: the command downloads the latest Guix source code and package
  1525. descriptions, and deploys it.
  1526. On completion, @command{guix package} will use packages and package
  1527. versions from this just-retrieved copy of Guix. Not only that, but all
  1528. the Guix commands and Scheme modules will also be taken from that latest
  1529. version. New @command{guix} sub-commands added by the update also
  1530. become available@footnote{Under the hood, @command{guix pull} updates
  1531. the @file{~/.config/guix/latest} symbolic link to point to the latest
  1532. Guix, and the @command{guix} command loads code from there.}.
  1533. The @command{guix pull} command is usually invoked with no arguments,
  1534. but it supports the following options:
  1535. @table @code
  1536. @item --verbose
  1537. Produce verbose output, writing build logs to the standard error output.
  1538. @item --url=@var{url}
  1539. Download the source tarball of Guix from @var{url}.
  1540. By default, the tarball is taken from its canonical address at
  1541. @code{gnu.org}, for the stable branch of Guix.
  1542. @item --bootstrap
  1543. Use the bootstrap Guile to build the latest Guix. This option is only
  1544. useful to Guix developers.
  1545. @end table
  1546. @node Invoking guix archive
  1547. @section Invoking @command{guix archive}
  1548. The @command{guix archive} command allows users to @dfn{export} files
  1549. from the store into a single archive, and to later @dfn{import} them.
  1550. In particular, it allows store files to be transferred from one machine
  1551. to another machine's store. For example, to transfer the @code{emacs}
  1552. package to a machine connected over SSH, one would run:
  1553. @example
  1554. guix archive --export -r emacs | ssh the-machine guix archive --import
  1555. @end example
  1556. @noindent
  1557. Similarly, a complete user profile may be transferred from one machine
  1558. to another like this:
  1559. @example
  1560. guix archive --export -r $(readlink -f ~/.guix-profile) | \
  1561. ssh the-machine guix-archive --import
  1562. @end example
  1563. @noindent
  1564. However, note that, in both examples, all of @code{emacs} and the
  1565. profile as well as all of their dependencies are transferred (due to
  1566. @code{-r}), regardless of what is already available in the target
  1567. machine's store. The @code{--missing} option can help figure out which
  1568. items are missing from the target's store.
  1569. Archives are stored in the ``Nix archive'' or ``Nar'' format, which is
  1570. comparable in spirit to `tar', but with a few noteworthy differences
  1571. that make it more appropriate for our purposes. First, rather than
  1572. recording all Unix meta-data for each file, the Nar format only mentions
  1573. the file type (regular, directory, or symbolic link); Unix permissions
  1574. and owner/group are dismissed. Second, the order in which directory
  1575. entries are stored always follows the order of file names according to
  1576. the C locale collation order. This makes archive production fully
  1577. deterministic.
  1578. When exporting, the daemon digitally signs the contents of the archive,
  1579. and that digital signature is appended. When importing, the daemon
  1580. verifies the signature and rejects the import in case of an invalid
  1581. signature or if the signing key is not authorized.
  1582. @c FIXME: Add xref to daemon doc about signatures.
  1583. The main options are:
  1584. @table @code
  1585. @item --export
  1586. Export the specified store files or packages (see below.) Write the
  1587. resulting archive to the standard output.
  1588. Dependencies are @emph{not} included in the output, unless
  1589. @code{--recursive} is passed.
  1590. @item -r
  1591. @itemx --recursive
  1592. When combined with @code{--export}, this instructs @command{guix
  1593. archive} to include dependencies of the given items in the archive.
  1594. Thus, the resulting archive is self-contained: it contains the closure
  1595. of the exported store items.
  1596. @item --import
  1597. Read an archive from the standard input, and import the files listed
  1598. therein into the store. Abort if the archive has an invalid digital
  1599. signature, or if it is signed by a public key not among the authorized
  1600. keys (see @code{--authorize} below.)
  1601. @item --missing
  1602. Read a list of store file names from the standard input, one per line,
  1603. and write on the standard output the subset of these files missing from
  1604. the store.
  1605. @item --generate-key[=@var{parameters}]
  1606. @cindex signing, archives
  1607. Generate a new key pair for the daemons. This is a prerequisite before
  1608. archives can be exported with @code{--export}. Note that this operation
  1609. usually takes time, because it needs to gather enough entropy to
  1610. generate the key pair.
  1611. The generated key pair is typically stored under @file{/etc/guix}, in
  1612. @file{signing-key.pub} (public key) and @file{signing-key.sec} (private
  1613. key, which must be kept secret.) When @var{parameters} is omitted,
  1614. an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
  1615. versions before 1.6.0, it is a 4096-bit RSA key.
  1616. Alternately, @var{parameters} can specify
  1617. @code{genkey} parameters suitable for Libgcrypt (@pxref{General
  1618. public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
  1619. Libgcrypt Reference Manual}).
  1620. @item --authorize
  1621. @cindex authorizing, archives
  1622. Authorize imports signed by the public key passed on standard input.
  1623. The public key must be in ``s-expression advanced format''---i.e., the
  1624. same format as the @file{signing-key.pub} file.
  1625. The list of authorized keys is kept in the human-editable file
  1626. @file{/etc/guix/acl}. The file contains
  1627. @url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
  1628. s-expressions''} and is structured as an access-control list in the
  1629. @url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
  1630. (SPKI)}.
  1631. @item --extract=@var{directory}
  1632. @itemx -x @var{directory}
  1633. Read a single-item archive as served by substitute servers
  1634. (@pxref{Substitutes}) and extract it to @var{directory}. This is a
  1635. low-level operation needed in only very narrow use cases; see below.
  1636. For example, the following command extracts the substitute for Emacs
  1637. served by @code{hydra.gnu.org} to @file{/tmp/emacs}:
  1638. @example
  1639. $ wget -O - \
  1640. http://hydra.gnu.org/nar/@dots{}-emacs-24.5 \
  1641. | bunzip2 | guix archive -x /tmp/emacs
  1642. @end example
  1643. Single-item archives are different from multiple-item archives produced
  1644. by @command{guix archive --export}; they contain a single store item,
  1645. and they do @emph{not} embed a signature. Thus this operation does
  1646. @emph{no} signature verification and its output should be considered
  1647. unsafe.
  1648. The primary purpose of this operation is to facilitate inspection of
  1649. archive contents coming from possibly untrusted substitute servers.
  1650. @end table
  1651. To export store files as an archive to the standard output, run:
  1652. @example
  1653. guix archive --export @var{options} @var{specifications}...
  1654. @end example
  1655. @var{specifications} may be either store file names or package
  1656. specifications, as for @command{guix package} (@pxref{Invoking guix
  1657. package}). For instance, the following command creates an archive
  1658. containing the @code{gui} output of the @code{git} package and the main
  1659. output of @code{emacs}:
  1660. @example
  1661. guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
  1662. @end example
  1663. If the specified packages are not built yet, @command{guix archive}
  1664. automatically builds them. The build process may be controlled with the
  1665. same options that can be passed to the @command{guix build} command
  1666. (@pxref{Invoking guix build, common build options}).
  1667. @c *********************************************************************
  1668. @include emacs.texi
  1669. @c *********************************************************************
  1670. @node Programming Interface
  1671. @chapter Programming Interface
  1672. GNU Guix provides several Scheme programming interfaces (APIs) to
  1673. define, build, and query packages. The first interface allows users to
  1674. write high-level package definitions. These definitions refer to
  1675. familiar packaging concepts, such as the name and version of a package,
  1676. its build system, and its dependencies. These definitions can then be
  1677. turned into concrete build actions.
  1678. Build actions are performed by the Guix daemon, on behalf of users. In a
  1679. standard setup, the daemon has write access to the store---the
  1680. @file{/gnu/store} directory---whereas users do not. The recommended
  1681. setup also has the daemon perform builds in chroots, under a specific
  1682. build users, to minimize interference with the rest of the system.
  1683. @cindex derivation
  1684. Lower-level APIs are available to interact with the daemon and the
  1685. store. To instruct the daemon to perform a build action, users actually
  1686. provide it with a @dfn{derivation}. A derivation is a low-level
  1687. representation of the build actions to be taken, and the environment in
  1688. which they should occur---derivations are to package definitions what
  1689. assembly is to C programs. The term ``derivation'' comes from the fact
  1690. that build results @emph{derive} from them.
  1691. This chapter describes all these APIs in turn, starting from high-level
  1692. package definitions.
  1693. @menu
  1694. * Defining Packages:: Defining new packages.
  1695. * Build Systems:: Specifying how packages are built.
  1696. * The Store:: Manipulating the package store.
  1697. * Derivations:: Low-level interface to package derivations.
  1698. * The Store Monad:: Purely functional interface to the store.
  1699. * G-Expressions:: Manipulating build expressions.
  1700. @end menu
  1701. @node Defining Packages
  1702. @section Defining Packages
  1703. The high-level interface to package definitions is implemented in the
  1704. @code{(guix packages)} and @code{(guix build-system)} modules. As an
  1705. example, the package definition, or @dfn{recipe}, for the GNU Hello
  1706. package looks like this:
  1707. @example
  1708. (define-module (gnu packages hello)
  1709. #:use-module (guix packages)
  1710. #:use-module (guix download)
  1711. #:use-module (guix build-system gnu)
  1712. #:use-module (guix licenses)
  1713. #:use-module (gnu packages gawk))
  1714. (define-public hello
  1715. (package
  1716. (name "hello")
  1717. (version "2.10")
  1718. (source (origin
  1719. (method url-fetch)
  1720. (uri (string-append "mirror://gnu/hello/hello-" version
  1721. ".tar.gz"))
  1722. (sha256
  1723. (base32
  1724. "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
  1725. (build-system gnu-build-system)
  1726. (arguments `(#:configure-flags '("--enable-silent-rules")))
  1727. (inputs `(("gawk" ,gawk)))
  1728. (synopsis "Hello, GNU world: An example GNU package")
  1729. (description "Guess what GNU Hello prints!")
  1730. (home-page "http://www.gnu.org/software/hello/")
  1731. (license gpl3+)))
  1732. @end example
  1733. @noindent
  1734. Without being a Scheme expert, the reader may have guessed the meaning
  1735. of the various fields here. This expression binds variable @code{hello}
  1736. to a @code{<package>} object, which is essentially a record
  1737. (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
  1738. This package object can be inspected using procedures found in the
  1739. @code{(guix packages)} module; for instance, @code{(package-name hello)}
  1740. returns---surprise!---@code{"hello"}.
  1741. With luck, you may be able to import part or all of the definition of
  1742. the package you are interested in from another repository, using the
  1743. @code{guix import} command (@pxref{Invoking guix import}).
  1744. In the example above, @var{hello} is defined into a module of its own,
  1745. @code{(gnu packages hello)}. Technically, this is not strictly
  1746. necessary, but it is convenient to do so: all the packages defined in
  1747. modules under @code{(gnu packages @dots{})} are automatically known to
  1748. the command-line tools (@pxref{Package Modules}).
  1749. There are a few points worth noting in the above package definition:
  1750. @itemize
  1751. @item
  1752. The @code{source} field of the package is an @code{<origin>} object
  1753. (@pxref{origin Reference}, for the complete reference).
  1754. Here, the @code{url-fetch} method from @code{(guix download)} is used,
  1755. meaning that the source is a file to be downloaded over FTP or HTTP.
  1756. The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
  1757. the GNU mirrors defined in @code{(guix download)}.
  1758. The @code{sha256} field specifies the expected SHA256 hash of the file
  1759. being downloaded. It is mandatory, and allows Guix to check the
  1760. integrity of the file. The @code{(base32 @dots{})} form introduces the
  1761. base32 representation of the hash. You can obtain this information with
  1762. @code{guix download} (@pxref{Invoking guix download}) and @code{guix
  1763. hash} (@pxref{Invoking guix hash}).
  1764. @cindex patches
  1765. When needed, the @code{origin} form can also have a @code{patches} field
  1766. listing patches to be applied, and a @code{snippet} field giving a
  1767. Scheme expression to modify the source code.
  1768. @item
  1769. @cindex GNU Build System
  1770. The @code{build-system} field specifies the procedure to build the
  1771. package (@pxref{Build Systems}). Here, @var{gnu-build-system}
  1772. represents the familiar GNU Build System, where packages may be
  1773. configured, built, and installed with the usual @code{./configure &&
  1774. make && make check && make install} command sequence.
  1775. @item
  1776. The @code{arguments} field specifies options for the build system
  1777. (@pxref{Build Systems}). Here it is interpreted by
  1778. @var{gnu-build-system} as a request run @file{configure} with the
  1779. @code{--enable-silent-rules} flag.
  1780. @item
  1781. The @code{inputs} field specifies inputs to the build process---i.e.,
  1782. build-time or run-time dependencies of the package. Here, we define an
  1783. input called @code{"gawk"} whose value is that of the @var{gawk}
  1784. variable; @var{gawk} is itself bound to a @code{<package>} object.
  1785. Note that GCC, Coreutils, Bash, and other essential tools do not need to
  1786. be specified as inputs here. Instead, @var{gnu-build-system} takes care
  1787. of ensuring that they are present (@pxref{Build Systems}).
  1788. However, any other dependencies need to be specified in the
  1789. @code{inputs} field. Any dependency not specified here will simply be
  1790. unavailable to the build process, possibly leading to a build failure.
  1791. @end itemize
  1792. @xref{package Reference}, for a full description of possible fields.
  1793. Once a package definition is in place, the
  1794. package may actually be built using the @code{guix build} command-line
  1795. tool (@pxref{Invoking guix build}). You can easily jump back to the
  1796. package definition using the @command{guix edit} command
  1797. (@pxref{Invoking guix edit}).
  1798. @xref{Packaging Guidelines}, for
  1799. more information on how to test package definitions, and
  1800. @ref{Invoking guix lint}, for information on how to check a definition
  1801. for style conformance.
  1802. Eventually, updating the package definition to a new upstream version
  1803. can be partly automated by the @command{guix refresh} command
  1804. (@pxref{Invoking guix refresh}).
  1805. Behind the scenes, a derivation corresponding to the @code{<package>}
  1806. object is first computed by the @code{package-derivation} procedure.
  1807. That derivation is stored in a @code{.drv} file under @file{/gnu/store}.
  1808. The build actions it prescribes may then be realized by using the
  1809. @code{build-derivations} procedure (@pxref{The Store}).
  1810. @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
  1811. Return the @code{<derivation>} object of @var{package} for @var{system}
  1812. (@pxref{Derivations}).
  1813. @var{package} must be a valid @code{<package>} object, and @var{system}
  1814. must be a string denoting the target system type---e.g.,
  1815. @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
  1816. must be a connection to the daemon, which operates on the store
  1817. (@pxref{The Store}).
  1818. @end deffn
  1819. @noindent
  1820. @cindex cross-compilation
  1821. Similarly, it is possible to compute a derivation that cross-builds a
  1822. package for some other system:
  1823. @deffn {Scheme Procedure} package-cross-derivation @var{store} @
  1824. @var{package} @var{target} [@var{system}]
  1825. Return the @code{<derivation>} object of @var{package} cross-built from
  1826. @var{system} to @var{target}.
  1827. @var{target} must be a valid GNU triplet denoting the target hardware
  1828. and operating system, such as @code{"mips64el-linux-gnu"}
  1829. (@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
  1830. Configure and Build System}).
  1831. @end deffn
  1832. @menu
  1833. * package Reference :: The package data type.
  1834. * origin Reference:: The origin data type.
  1835. @end menu
  1836. @node package Reference
  1837. @subsection @code{package} Reference
  1838. This section summarizes all the options available in @code{package}
  1839. declarations (@pxref{Defining Packages}).
  1840. @deftp {Data Type} package
  1841. This is the data type representing a package recipe.
  1842. @table @asis
  1843. @item @code{name}
  1844. The name of the package, as a string.
  1845. @item @code{version}
  1846. The version of the package, as a string.
  1847. @item @code{source}
  1848. An origin object telling how the source code for the package should be
  1849. acquired (@pxref{origin Reference}).
  1850. @item @code{build-system}
  1851. The build system that should be used to build the package (@pxref{Build
  1852. Systems}).
  1853. @item @code{arguments} (default: @code{'()})
  1854. The arguments that should be passed to the build system. This is a
  1855. list, typically containing sequential keyword-value pairs.
  1856. @item @code{inputs} (default: @code{'()})
  1857. @itemx @code{native-inputs} (default: @code{'()})
  1858. @itemx @code{propagated-inputs} (default: @code{'()})
  1859. @cindex inputs, of packages
  1860. These fields list dependencies of the package. Each one is a list of
  1861. tuples, where each tuple has a label for the input (a string) as its
  1862. first element, a package, origin, or derivation as its second element,
  1863. and optionally the name of the output thereof that should be used, which
  1864. defaults to @code{"out"} (@pxref{Packages with Multiple Outputs}, for
  1865. more on package outputs). For example, the list below specifies 3
  1866. inputs:
  1867. @example
  1868. `(("libffi" ,libffi)
  1869. ("libunistring" ,libunistring)
  1870. ("glib:bin" ,glib "bin")) ;the "bin" output of Glib
  1871. @end example
  1872. @cindex cross compilation, package dependencies
  1873. The distinction between @code{native-inputs} and @code{inputs} is
  1874. necessary when considering cross-compilation. When cross-compiling,
  1875. dependencies listed in @code{inputs} are built for the @emph{target}
  1876. architecture; conversely, dependencies listed in @code{native-inputs}
  1877. are built for the architecture of the @emph{build} machine.
  1878. @code{native-inputs} is typically where you would list tools needed at
  1879. build time but not at run time, such as Autoconf, Automake, pkg-config,
  1880. Gettext, or Bison. @command{guix lint} can report likely mistakes in
  1881. this area (@pxref{Invoking guix lint}).
  1882. @anchor{package-propagated-inputs}
  1883. Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
  1884. specified packages will be force-installed alongside the package they
  1885. belong to (@pxref{package-cmd-propagated-inputs, @command{guix
  1886. package}}, for information on how @command{guix package} deals with
  1887. propagated inputs.)
  1888. For example this is necessary when a C/C++ library needs headers of
  1889. another library to compile, or when a pkg-config file refers to another
  1890. one @i{via} its @code{Requires} field.
  1891. Another example where @code{propagated-inputs} is useful is for
  1892. languages that lack a facility to record the run-time search path akin
  1893. to ELF's @code{RUNPATH}; this includes Guile, Python, Perl, GHC, and
  1894. more. To ensure that libraries written in those languages can find
  1895. library code they depend on at run time, run-time dependencies must be
  1896. listed in @code{propagated-inputs} rather than @code{inputs}.
  1897. @item @code{self-native-input?} (default: @code{#f})
  1898. This is a Boolean field telling whether the package should use itself as
  1899. a native input when cross-compiling.
  1900. @item @code{outputs} (default: @code{'("out")})
  1901. The list of output names of the package. @xref{Packages with Multiple
  1902. Outputs}, for typical uses of additional outputs.
  1903. @item @code{native-search-paths} (default: @code{'()})
  1904. @itemx @code{search-paths} (default: @code{'()})
  1905. A list of @code{search-path-specification} objects describing
  1906. search-path environment variables honored by the package.
  1907. @item @code{replacement} (default: @code{#f})
  1908. This must either @code{#f} or a package object that will be used as a
  1909. @dfn{replacement} for this package. @xref{Security Updates, grafts},
  1910. for details.
  1911. @item @code{synopsis}
  1912. A one-line description of the package.
  1913. @item @code{description}
  1914. A more elaborate description of the package.
  1915. @item @code{license}
  1916. The license of the package; a value from @code{(guix licenses)}.
  1917. @item @code{home-page}
  1918. The URL to the home-page of the package, as a string.
  1919. @item @code{supported-systems} (default: @var{%supported-systems})
  1920. The list of systems supported by the package, as strings of the form
  1921. @code{architecture-kernel}, for example @code{"x86_64-linux"}.
  1922. @item @code{maintainers} (default: @code{'()})
  1923. The list of maintainers of the package, as @code{maintainer} objects.
  1924. @item @code{location} (default: source location of the @code{package} form)
  1925. The source location of the package. It's useful to override this when
  1926. inheriting from another package, in which case this field is not
  1927. automatically corrected.
  1928. @end table
  1929. @end deftp
  1930. @node origin Reference
  1931. @subsection @code{origin} Reference
  1932. This section summarizes all the options available in @code{origin}
  1933. declarations (@pxref{Defining Packages}).
  1934. @deftp {Data Type} origin
  1935. This is the data type representing a source code origin.
  1936. @table @asis
  1937. @item @code{uri}
  1938. An object containing the URI of the source. The object type depends on
  1939. the @code{method} (see below). For example, when using the
  1940. @var{url-fetch} method of @code{(guix download)}, the valid @code{uri}
  1941. values are: a URL represented as a string, or a list thereof.
  1942. @item @code{method}
  1943. A procedure that will handle the URI.
  1944. Examples include:
  1945. @table @asis
  1946. @item @var{url-fetch} from @code{(guix download)}
  1947. download a file the HTTP, HTTPS, or FTP URL specified in the
  1948. @code{uri} field;
  1949. @item @var{git-fetch} from @code{(guix git-download)}
  1950. clone the Git version control repository, and check out the revision
  1951. specified in the @code{uri} field as a @code{git-reference} object; a
  1952. @code{git-reference} looks like this:
  1953. @example
  1954. (git-reference
  1955. (url "git://git.debian.org/git/pkg-shadow/shadow")
  1956. (commit "v4.1.5.1"))
  1957. @end example
  1958. @end table
  1959. @item @code{sha256}
  1960. A bytevector containing the SHA-256 hash of the source. Typically the
  1961. @code{base32} form is used here to generate the bytevector from a
  1962. base-32 string.
  1963. @item @code{file-name} (default: @code{#f})
  1964. The file name under which the source code should be saved. When this is
  1965. @code{#f}, a sensible default value will be used in most cases. In case
  1966. the source is fetched from a URL, the file name from the URL will be
  1967. used. For version control checkouts, it's recommended to provide the
  1968. file name explicitly because the default is not very descriptive.
  1969. @item @code{patches} (default: @code{'()})
  1970. A list of file names containing patches to be applied to the source.
  1971. @item @code{snippet} (default: @code{#f})
  1972. A quoted piece of code that will be run in the source directory to make
  1973. any modifications, which is sometimes more convenient than a patch.
  1974. @item @code{patch-flags} (default: @code{'("-p1")})
  1975. A list of command-line flags that should be passed to the @code{patch}
  1976. command.
  1977. @item @code{patch-inputs} (default: @code{#f})
  1978. Input packages or derivations to the patching process. When this is
  1979. @code{#f}, the usual set of inputs necessary for patching are provided,
  1980. such as GNU@tie{}Patch.
  1981. @item @code{modules} (default: @code{'()})
  1982. A list of Guile modules that should be loaded during the patching
  1983. process and while running the code in the @code{snippet} field.
  1984. @item @code{imported-modules} (default: @code{'()})
  1985. The list of Guile modules to import in the patch derivation, for use by
  1986. the @code{snippet}.
  1987. @item @code{patch-guile} (default: @code{#f})
  1988. The Guile package that should be used in the patching process. When
  1989. this is @code{#f}, a sensible default is used.
  1990. @end table
  1991. @end deftp
  1992. @node Build Systems
  1993. @section Build Systems
  1994. @cindex build system
  1995. Each package definition specifies a @dfn{build system} and arguments for
  1996. that build system (@pxref{Defining Packages}). This @code{build-system}
  1997. field represents the build procedure of the package, as well implicit
  1998. dependencies of that build procedure.
  1999. Build systems are @code{<build-system>} objects. The interface to
  2000. create and manipulate them is provided by the @code{(guix build-system)}
  2001. module, and actual build systems are exported by specific modules.
  2002. @cindex bag (low-level package representation)
  2003. Under the hood, build systems first compile package objects to
  2004. @dfn{bags}. A @dfn{bag} is like a package, but with less
  2005. ornamentation---in other words, a bag is a lower-level representation of
  2006. a package, which includes all the inputs of that package, including some
  2007. that were implicitly added by the build system. This intermediate
  2008. representation is then compiled to a derivation (@pxref{Derivations}).
  2009. Build systems accept an optional list of @dfn{arguments}. In package
  2010. definitions, these are passed @i{via} the @code{arguments} field
  2011. (@pxref{Defining Packages}). They are typically keyword arguments
  2012. (@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
  2013. Guile Reference Manual}). The value of these arguments is usually
  2014. evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
  2015. by the daemon (@pxref{Derivations}).
  2016. The main build system is @var{gnu-build-system}, which implements the
  2017. standard build procedure for GNU packages and many other packages. It
  2018. is provided by the @code{(guix build-system gnu)} module.
  2019. @defvr {Scheme Variable} gnu-build-system
  2020. @var{gnu-build-system} represents the GNU Build System, and variants
  2021. thereof (@pxref{Configuration, configuration and makefile conventions,,
  2022. standards, GNU Coding Standards}).
  2023. @cindex build phases
  2024. In a nutshell, packages using it configured, built, and installed with
  2025. the usual @code{./configure && make && make check && make install}
  2026. command sequence. In practice, a few additional steps are often needed.
  2027. All these steps are split up in separate @dfn{phases},
  2028. notably@footnote{Please see the @code{(guix build gnu-build-system)}
  2029. modules for more details about the build phases.}:
  2030. @table @code
  2031. @item unpack
  2032. Unpack the source tarball, and change the current directory to the
  2033. extracted source tree. If the source is actually a directory, copy it
  2034. to the build tree, and enter that directory.
  2035. @item patch-source-shebangs
  2036. Patch shebangs encountered in source files so they refer to the right
  2037. store file names. For instance, this changes @code{#!/bin/sh} to
  2038. @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
  2039. @item configure
  2040. Run the @file{configure} script with a number of default options, such
  2041. as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
  2042. by the @code{#:configure-flags} argument.
  2043. @item build
  2044. Run @code{make} with the list of flags specified with
  2045. @code{#:make-flags}. If the @code{#:parallel-builds?} argument is true
  2046. (the default), build with @code{make -j}.
  2047. @item check
  2048. Run @code{make check}, or some other target specified with
  2049. @code{#:test-target}, unless @code{#:tests? #f} is passed. If the
  2050. @code{#:parallel-tests?} argument is true (the default), run @code{make
  2051. check -j}.
  2052. @item install
  2053. Run @code{make install} with the flags listed in @code{#:make-flags}.
  2054. @item patch-shebangs
  2055. Patch shebangs on the installed executable files.
  2056. @item strip
  2057. Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
  2058. is false), copying them to the @code{debug} output when available
  2059. (@pxref{Installing Debugging Files}).
  2060. @end table
  2061. @vindex %standard-phases
  2062. The build-side module @code{(guix build gnu-build-system)} defines
  2063. @var{%standard-phases} as the default list of build phases.
  2064. @var{%standard-phases} is a list of symbol/procedure pairs, where the
  2065. procedure implements the actual phase.
  2066. The list of phases used for a particular package can be changed with the
  2067. @code{#:phases} parameter. For instance, passing:
  2068. @example
  2069. #:phases (alist-delete 'configure %standard-phases)
  2070. @end example
  2071. means that all the phases described above will be used, except the
  2072. @code{configure} phase.
  2073. In addition, this build system ensures that the ``standard'' environment
  2074. for GNU packages is available. This includes tools such as GCC, libc,
  2075. Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
  2076. build-system gnu)} module for a complete list.) We call these the
  2077. @dfn{implicit inputs} of a package, because package definitions don't
  2078. have to mention them.
  2079. @end defvr
  2080. Other @code{<build-system>} objects are defined to support other
  2081. conventions and tools used by free software packages. They inherit most
  2082. of @var{gnu-build-system}, and differ mainly in the set of inputs
  2083. implicitly added to the build process, and in the list of phases
  2084. executed. Some of these build systems are listed below.
  2085. @defvr {Scheme Variable} cmake-build-system
  2086. This variable is exported by @code{(guix build-system cmake)}. It
  2087. implements the build procedure for packages using the
  2088. @url{http://www.cmake.org, CMake build tool}.
  2089. It automatically adds the @code{cmake} package to the set of inputs.
  2090. Which package is used can be specified with the @code{#:cmake}
  2091. parameter.
  2092. The @code{#:configure-flags} parameter is taken as a list of flags
  2093. passed to the @command{cmake} command. The @code{#:build-type}
  2094. parameter specifies in abstract terms the flags passed to the compiler;
  2095. it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
  2096. debugging information''), which roughly means that code is compiled with
  2097. @code{-O2 -g}, as is the case for Autoconf-based packages by default.
  2098. @end defvr
  2099. @defvr {Scheme Variable} glib-or-gtk-build-system
  2100. This variable is exported by @code{(guix build-system glib-or-gtk)}. It
  2101. is intended for use with packages making use of GLib or GTK+.
  2102. This build system adds the following two phases to the ones defined by
  2103. @var{gnu-build-system}:
  2104. @table @code
  2105. @item glib-or-gtk-wrap
  2106. The phase @code{glib-or-gtk-wrap} ensures that programs found under
  2107. @file{bin/} are able to find GLib's ``schemas'' and
  2108. @uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
  2109. modules}. This is achieved by wrapping the programs in launch scripts
  2110. that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
  2111. environment variables.
  2112. It is possible to exclude specific package outputs from that wrapping
  2113. process by listing their names in the
  2114. @code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
  2115. when an output is known not to contain any GLib or GTK+ binaries, and
  2116. where wrapping would gratuitously add a dependency of that output on
  2117. GLib and GTK+.
  2118. @item glib-or-gtk-compile-schemas
  2119. The phase @code{glib-or-gtk-compile-schemas} makes sure that all GLib's
  2120. @uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
  2121. GSettings schemas} are compiled. Compilation is performed by the
  2122. @command{glib-compile-schemas} program. It is provided by the package
  2123. @code{glib:bin} which is automatically imported by the build system.
  2124. The @code{glib} package providing @command{glib-compile-schemas} can be
  2125. specified with the @code{#:glib} parameter.
  2126. @end table
  2127. Both phases are executed after the @code{install} phase.
  2128. @end defvr
  2129. @defvr {Scheme Variable} python-build-system
  2130. This variable is exported by @code{(guix build-system python)}. It
  2131. implements the more or less standard build procedure used by Python
  2132. packages, which consists in running @code{python setup.py build} and
  2133. then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
  2134. For packages that install stand-alone Python programs under @code{bin/},
  2135. it takes care of wrapping these programs so their @code{PYTHONPATH}
  2136. environment variable points to all the Python libraries they depend on.
  2137. Which Python package is used can be specified with the @code{#:python}
  2138. parameter.
  2139. @end defvr
  2140. @defvr {Scheme Variable} perl-build-system
  2141. This variable is exported by @code{(guix build-system perl)}. It
  2142. implements the standard build procedure for Perl packages, which either
  2143. consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
  2144. followed by @code{Build} and @code{Build install}; or in running
  2145. @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
  2146. @code{make} and @code{make install}; depending on which of
  2147. @code{Build.PL} or @code{Makefile.PL} is present in the package
  2148. distribution. Preference is given to the former if both @code{Build.PL}
  2149. and @code{Makefile.PL} exist in the package distribution. This
  2150. preference can be reversed by specifying @code{#t} for the
  2151. @code{#:make-maker?} parameter.
  2152. The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
  2153. passes flags specified by the @code{#:make-maker-flags} or
  2154. @code{#:module-build-flags} parameter, respectively.
  2155. Which Perl package is used can be specified with @code{#:perl}.
  2156. @end defvr
  2157. @defvr {Scheme Variable} r-build-system
  2158. This variable is exported by @code{(guix build-system r)}. It
  2159. implements the build procedure used by @uref{http://r-project.org, R}
  2160. packages, which essentially is little more than running @code{R CMD
  2161. INSTALL --library=/gnu/store/@dots{}} in an environment where
  2162. @code{R_LIBS_SITE} contains the paths to all R package inputs. Tests
  2163. are run after installation using the R function
  2164. @code{tools::testInstalledPackage}.
  2165. @end defvr
  2166. @defvr {Scheme Variable} ruby-build-system
  2167. This variable is exported by @code{(guix build-system ruby)}. It
  2168. implements the RubyGems build procedure used by Ruby packages, which
  2169. involves running @code{gem build} followed by @code{gem install}.
  2170. The @code{source} field of a package that uses this build system
  2171. typically references a gem archive, since this is the format that Ruby
  2172. developers use when releasing their software. The build system unpacks
  2173. the gem archive, potentially patches the source, runs the test suite,
  2174. repackages the gem, and installs it. Additionally, directories and
  2175. tarballs may be referenced to allow building unreleased gems from Git or
  2176. a traditional source release tarball.
  2177. Which Ruby package is used can be specified with the @code{#:ruby}
  2178. parameter. A list of additional flags to be passed to the @command{gem}
  2179. command can be specified with the @code{#:gem-flags} parameter.
  2180. @end defvr
  2181. @defvr {Scheme Variable} waf-build-system
  2182. This variable is exported by @code{(guix build-system waf)}. It
  2183. implements a build procedure around the @code{waf} script. The common
  2184. phases---@code{configure}, @code{build}, and @code{install}---are
  2185. implemented by passing their names as arguments to the @code{waf}
  2186. script.
  2187. The @code{waf} script is executed by the Python interpreter. Which
  2188. Python package is used to run the script can be specified with the
  2189. @code{#:python} parameter.
  2190. @end defvr
  2191. @defvr {Scheme Variable} haskell-build-system
  2192. This variable is exported by @code{(guix build-system haskell)}. It
  2193. implements the Cabal build procedure used by Haskell packages, which
  2194. involves running @code{runhaskell Setup.hs configure
  2195. --prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.
  2196. Instead of installing the package by running @code{runhaskell Setup.hs
  2197. install}, to avoid trying to register libraries in the read-only
  2198. compiler store directory, the build system uses @code{runhaskell
  2199. Setup.hs copy}, followed by @code{runhaskell Setup.hs register}. In
  2200. addition, the build system generates the package documentation by
  2201. running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f}
  2202. is passed. Optional Haddock parameters can be passed with the help of
  2203. the @code{#:haddock-flags} parameter. If the file @code{Setup.hs} is
  2204. not found, the build system looks for @code{Setup.lhs} instead.
  2205. Which Haskell compiler is used can be specified with the @code{#:haskell}
  2206. parameter which defaults to @code{ghc}.
  2207. @end defvr
  2208. @defvr {Scheme Variable} emacs-build-system
  2209. This variable is exported by @code{(guix build-system emacs)}. It
  2210. implements an installation procedure similar to the one of Emacs' own
  2211. packaging system (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
  2212. It first creates the @code{@var{package}-autoloads.el} file, then it
  2213. byte compiles all Emacs Lisp files. Differently from the Emacs
  2214. packaging system, the Info documentation files are moved to the standard
  2215. documentation directory and the @file{dir} file is deleted. Each
  2216. package is installed in its own directory under
  2217. @file{share/emacs/site-lisp/guix.d}.
  2218. @end defvr
  2219. Lastly, for packages that do not need anything as sophisticated, a
  2220. ``trivial'' build system is provided. It is trivial in the sense that
  2221. it provides basically no support: it does not pull any implicit inputs,
  2222. and does not have a notion of build phases.
  2223. @defvr {Scheme Variable} trivial-build-system
  2224. This variable is exported by @code{(guix build-system trivial)}.
  2225. This build system requires a @code{#:builder} argument. This argument
  2226. must be a Scheme expression that builds the package's output(s)---as
  2227. with @code{build-expression->derivation} (@pxref{Derivations,
  2228. @code{build-expression->derivation}}).
  2229. @end defvr
  2230. @node The Store
  2231. @section The Store
  2232. @cindex store
  2233. @cindex store paths
  2234. Conceptually, the @dfn{store} is where derivations that have been
  2235. successfully built are stored---by default, under @file{/gnu/store}.
  2236. Sub-directories in the store are referred to as @dfn{store paths}. The
  2237. store has an associated database that contains information such as the
  2238. store paths referred to by each store path, and the list of @emph{valid}
  2239. store paths---paths that result from a successful build.
  2240. The store is always accessed by the daemon on behalf of its clients
  2241. (@pxref{Invoking guix-daemon}). To manipulate the store, clients
  2242. connect to the daemon over a Unix-domain socket, send it requests, and
  2243. read the result---these are remote procedure calls, or RPCs.
  2244. The @code{(guix store)} module provides procedures to connect to the
  2245. daemon, and to perform RPCs. These are described below.
  2246. @deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
  2247. Connect to the daemon over the Unix-domain socket at @var{file}. When
  2248. @var{reserve-space?} is true, instruct it to reserve a little bit of
  2249. extra space on the file system so that the garbage collector can still
  2250. operate, should the disk become full. Return a server object.
  2251. @var{file} defaults to @var{%default-socket-path}, which is the normal
  2252. location given the options that were passed to @command{configure}.
  2253. @end deffn
  2254. @deffn {Scheme Procedure} close-connection @var{server}
  2255. Close the connection to @var{server}.
  2256. @end deffn
  2257. @defvr {Scheme Variable} current-build-output-port
  2258. This variable is bound to a SRFI-39 parameter, which refers to the port
  2259. where build and error logs sent by the daemon should be written.
  2260. @end defvr
  2261. Procedures that make RPCs all take a server object as their first
  2262. argument.
  2263. @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
  2264. Return @code{#t} when @var{path} is a valid store path.
  2265. @end deffn
  2266. @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
  2267. Add @var{text} under file @var{name} in the store, and return its store
  2268. path. @var{references} is the list of store paths referred to by the
  2269. resulting store path.
  2270. @end deffn
  2271. @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
  2272. Build @var{derivations} (a list of @code{<derivation>} objects or
  2273. derivation paths), and return when the worker is done building them.
  2274. Return @code{#t} on success.
  2275. @end deffn
  2276. Note that the @code{(guix monads)} module provides a monad as well as
  2277. monadic versions of the above procedures, with the goal of making it
  2278. more convenient to work with code that accesses the store (@pxref{The
  2279. Store Monad}).
  2280. @c FIXME
  2281. @i{This section is currently incomplete.}
  2282. @node Derivations
  2283. @section Derivations
  2284. @cindex derivations
  2285. Low-level build actions and the environment in which they are performed
  2286. are represented by @dfn{derivations}. A derivation contain the
  2287. following pieces of information:
  2288. @itemize
  2289. @item
  2290. The outputs of the derivation---derivations produce at least one file or
  2291. directory in the store, but may produce more.
  2292. @item
  2293. The inputs of the derivations, which may be other derivations or plain
  2294. files in the store (patches, build scripts, etc.)
  2295. @item
  2296. The system type targeted by the derivation---e.g., @code{x86_64-linux}.
  2297. @item
  2298. The file name of a build script in the store, along with the arguments
  2299. to be passed.
  2300. @item
  2301. A list of environment variables to be defined.
  2302. @end itemize
  2303. @cindex derivation path
  2304. Derivations allow clients of the daemon to communicate build actions to
  2305. the store. They exist in two forms: as an in-memory representation,
  2306. both on the client- and daemon-side, and as files in the store whose
  2307. name end in @code{.drv}---these files are referred to as @dfn{derivation
  2308. paths}. Derivations paths can be passed to the @code{build-derivations}
  2309. procedure to perform the build actions they prescribe (@pxref{The
  2310. Store}).
  2311. The @code{(guix derivations)} module provides a representation of
  2312. derivations as Scheme objects, along with procedures to create and
  2313. otherwise manipulate derivations. The lowest-level primitive to create
  2314. a derivation is the @code{derivation} procedure:
  2315. @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
  2316. @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
  2317. [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
  2318. [#:system (%current-system)] [#:references-graphs #f] @
  2319. [#:allowed-references #f] [#:leaked-env-vars #f] [#:local-build? #f] @
  2320. [#:substitutable? #t]
  2321. Build a derivation with the given arguments, and return the resulting
  2322. @code{<derivation>} object.
  2323. When @var{hash} and @var{hash-algo} are given, a
  2324. @dfn{fixed-output derivation} is created---i.e., one whose result is
  2325. known in advance, such as a file download. If, in addition,
  2326. @var{recursive?} is true, then that fixed output may be an executable
  2327. file or a directory and @var{hash} must be the hash of an archive
  2328. containing this output.
  2329. When @var{references-graphs} is true, it must be a list of file
  2330. name/store path pairs. In that case, the reference graph of each store
  2331. path is exported in the build environment in the corresponding file, in
  2332. a simple text format.
  2333. When @var{allowed-references} is true, it must be a list of store items
  2334. or outputs that the derivation's output may refer to.
  2335. When @var{leaked-env-vars} is true, it must be a list of strings
  2336. denoting environment variables that are allowed to ``leak'' from the
  2337. daemon's environment to the build environment. This is only applicable
  2338. to fixed-output derivations---i.e., when @var{hash} is true. The main
  2339. use is to allow variables such as @code{http_proxy} to be passed to
  2340. derivations that download files.
  2341. When @var{local-build?} is true, declare that the derivation is not a
  2342. good candidate for offloading and should rather be built locally
  2343. (@pxref{Daemon Offload Setup}). This is the case for small derivations
  2344. where the costs of data transfers would outweigh the benefits.
  2345. When @var{substitutable?} is false, declare that substitutes of the
  2346. derivation's output should not be used (@pxref{Substitutes}). This is
  2347. useful, for instance, when building packages that capture details of the
  2348. host CPU instruction set.
  2349. @end deffn
  2350. @noindent
  2351. Here's an example with a shell script as its builder, assuming
  2352. @var{store} is an open connection to the daemon, and @var{bash} points
  2353. to a Bash executable in the store:
  2354. @lisp
  2355. (use-modules (guix utils)
  2356. (guix store)
  2357. (guix derivations))
  2358. (let ((builder ; add the Bash script to the store
  2359. (add-text-to-store store "my-builder.sh"
  2360. "echo hello world > $out\n" '())))
  2361. (derivation store "foo"
  2362. bash `("-e" ,builder)
  2363. #:inputs `((,bash) (,builder))
  2364. #:env-vars '(("HOME" . "/homeless"))))
  2365. @result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
  2366. @end lisp
  2367. As can be guessed, this primitive is cumbersome to use directly. A
  2368. better approach is to write build scripts in Scheme, of course! The
  2369. best course of action for that is to write the build code as a
  2370. ``G-expression'', and to pass it to @code{gexp->derivation}. For more
  2371. information, @pxref{G-Expressions}.
  2372. Once upon a time, @code{gexp->derivation} did not exist and constructing
  2373. derivations with build code written in Scheme was achieved with
  2374. @code{build-expression->derivation}, documented below. This procedure
  2375. is now deprecated in favor of the much nicer @code{gexp->derivation}.
  2376. @deffn {Scheme Procedure} build-expression->derivation @var{store} @
  2377. @var{name} @var{exp} @
  2378. [#:system (%current-system)] [#:inputs '()] @
  2379. [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
  2380. [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
  2381. [#:references-graphs #f] [#:allowed-references #f] @
  2382. [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f]
  2383. Return a derivation that executes Scheme expression @var{exp} as a
  2384. builder for derivation @var{name}. @var{inputs} must be a list of
  2385. @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
  2386. @code{"out"} is assumed. @var{modules} is a list of names of Guile
  2387. modules from the current search path to be copied in the store,
  2388. compiled, and made available in the load path during the execution of
  2389. @var{exp}---e.g., @code{((guix build utils) (guix build
  2390. gnu-build-system))}.
  2391. @var{exp} is evaluated in an environment where @code{%outputs} is bound
  2392. to a list of output/path pairs, and where @code{%build-inputs} is bound
  2393. to a list of string/output-path pairs made from @var{inputs}.
  2394. Optionally, @var{env-vars} is a list of string pairs specifying the name
  2395. and value of environment variables visible to the builder. The builder
  2396. terminates by passing the result of @var{exp} to @code{exit}; thus, when
  2397. @var{exp} returns @code{#f}, the build is considered to have failed.
  2398. @var{exp} is built using @var{guile-for-build} (a derivation). When
  2399. @var{guile-for-build} is omitted or is @code{#f}, the value of the
  2400. @code{%guile-for-build} fluid is used instead.
  2401. See the @code{derivation} procedure for the meaning of
  2402. @var{references-graphs}, @var{allowed-references}, @var{local-build?},
  2403. and @var{substitutable?}.
  2404. @end deffn
  2405. @noindent
  2406. Here's an example of a single-output derivation that creates a directory
  2407. containing one file:
  2408. @lisp
  2409. (let ((builder '(let ((out (assoc-ref %outputs "out")))
  2410. (mkdir out) ; create /gnu/store/@dots{}-goo
  2411. (call-with-output-file (string-append out "/test")
  2412. (lambda (p)
  2413. (display '(hello guix) p))))))
  2414. (build-expression->derivation store "goo" builder))
  2415. @result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
  2416. @end lisp
  2417. @node The Store Monad
  2418. @section The Store Monad
  2419. @cindex monad
  2420. The procedures that operate on the store described in the previous
  2421. sections all take an open connection to the build daemon as their first
  2422. argument. Although the underlying model is functional, they either have
  2423. side effects or depend on the current state of the store.
  2424. The former is inconvenient: the connection to the build daemon has to be
  2425. carried around in all those functions, making it impossible to compose
  2426. functions that do not take that parameter with functions that do. The
  2427. latter can be problematic: since store operations have side effects
  2428. and/or depend on external state, they have to be properly sequenced.
  2429. @cindex monadic values
  2430. @cindex monadic functions
  2431. This is where the @code{(guix monads)} module comes in. This module
  2432. provides a framework for working with @dfn{monads}, and a particularly
  2433. useful monad for our uses, the @dfn{store monad}. Monads are a
  2434. construct that allows two things: associating ``context'' with values
  2435. (in our case, the context is the store), and building sequences of
  2436. computations (here computations include accesses to the store.) Values
  2437. in a monad---values that carry this additional context---are called
  2438. @dfn{monadic values}; procedures that return such values are called
  2439. @dfn{monadic procedures}.
  2440. Consider this ``normal'' procedure:
  2441. @example
  2442. (define (sh-symlink store)
  2443. ;; Return a derivation that symlinks the 'bash' executable.
  2444. (let* ((drv (package-derivation store bash))
  2445. (out (derivation->output-path drv))
  2446. (sh (string-append out "/bin/bash")))
  2447. (build-expression->derivation store "sh"
  2448. `(symlink ,sh %output))))
  2449. @end example
  2450. Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten
  2451. as a monadic function:
  2452. @example
  2453. (define (sh-symlink)
  2454. ;; Same, but return a monadic value.
  2455. (mlet %store-monad ((drv (package->derivation bash)))
  2456. (gexp->derivation "sh"
  2457. #~(symlink (string-append #$drv "/bin/bash")
  2458. #$output))))
  2459. @end example
  2460. There several things to note in the second version: the @code{store}
  2461. parameter is now implicit and is ``threaded'' in the calls to the
  2462. @code{package->derivation} and @code{gexp->derivation} monadic
  2463. procedures, and the monadic value returned by @code{package->derivation}
  2464. is @dfn{bound} using @code{mlet} instead of plain @code{let}.
  2465. As it turns out, the call to @code{package->derivation} can even be
  2466. omitted since it will take place implicitly, as we will see later
  2467. (@pxref{G-Expressions}):
  2468. @example
  2469. (define (sh-symlink)
  2470. (gexp->derivation "sh"
  2471. #~(symlink (string-append #$bash "/bin/bash")
  2472. #$output)))
  2473. @end example
  2474. @c See
  2475. @c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/>
  2476. @c for the funny quote.
  2477. Calling the monadic @code{sh-symlink} has no effect. As someone once
  2478. said, ``you exit a monad like you exit a building on fire: by running''.
  2479. So, to exit the monad and get the desired effect, one must use
  2480. @code{run-with-store}:
  2481. @example
  2482. (run-with-store (open-connection) (sh-symlink))
  2483. @result{} /gnu/store/...-sh-symlink
  2484. @end example
  2485. Note that the @code{(guix monad-repl)} module extends Guile's REPL with
  2486. new ``meta-commands'' to make it easier to deal with monadic procedures:
  2487. @code{run-in-store}, and @code{enter-store-monad}. The former, is used
  2488. to ``run'' a single monadic value through the store:
  2489. @example
  2490. scheme@@(guile-user)> ,run-in-store (package->derivation hello)
  2491. $1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
  2492. @end example
  2493. The latter enters a recursive REPL, where all the return values are
  2494. automatically run through the store:
  2495. @example
  2496. scheme@@(guile-user)> ,enter-store-monad
  2497. store-monad@@(guile-user) [1]> (package->derivation hello)
  2498. $2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
  2499. store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
  2500. $3 = "/gnu/store/@dots{}-foo"
  2501. store-monad@@(guile-user) [1]> ,q
  2502. scheme@@(guile-user)>
  2503. @end example
  2504. @noindent
  2505. Note that non-monadic values cannot be returned in the
  2506. @code{store-monad} REPL.
  2507. The main syntactic forms to deal with monads in general are provided by
  2508. the @code{(guix monads)} module and are described below.
  2509. @deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
  2510. Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
  2511. in @var{monad}.
  2512. @end deffn
  2513. @deffn {Scheme Syntax} return @var{val}
  2514. Return a monadic value that encapsulates @var{val}.
  2515. @end deffn
  2516. @deffn {Scheme Syntax} >>= @var{mval} @var{mproc} ...
  2517. @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
  2518. procedures @var{mproc}@dots{}@footnote{This operation is commonly
  2519. referred to as ``bind'', but that name denotes an unrelated procedure in
  2520. Guile. Thus we use this somewhat cryptic symbol inherited from the
  2521. Haskell language.}. There can be one @var{mproc} or several of them, as
  2522. in this example:
  2523. @example
  2524. (run-with-state
  2525. (with-monad %state-monad
  2526. (>>= (return 1)
  2527. (lambda (x) (return (+ 1 x)))
  2528. (lambda (x) (return (* 2 x)))))
  2529. 'some-state)
  2530. @result{} 4
  2531. @result{} some-state
  2532. @end example
  2533. @end deffn
  2534. @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
  2535. @var{body} ...
  2536. @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
  2537. @var{body} ...
  2538. Bind the variables @var{var} to the monadic values @var{mval} in
  2539. @var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the
  2540. ``normal'' value @var{val}, as per @code{let}.
  2541. @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
  2542. (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
  2543. @end deffn
  2544. @deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
  2545. Bind @var{mexp} and the following monadic expressions in sequence,
  2546. returning the result of the last expression.
  2547. This is akin to @code{mlet}, except that the return values of the
  2548. monadic expressions are ignored. In that sense, it is analogous to
  2549. @code{begin}, but applied to monadic expressions.
  2550. @end deffn
  2551. @cindex state monad
  2552. The @code{(guix monads)} module provides the @dfn{state monad}, which
  2553. allows an additional value---the state---to be @emph{threaded} through
  2554. monadic procedure calls.
  2555. @defvr {Scheme Variable} %state-monad
  2556. The state monad. Procedures in the state monad can access and change
  2557. the state that is threaded.
  2558. Consider the example below. The @code{square} procedure returns a value
  2559. in the state monad. It returns the square of its argument, but also
  2560. increments the current state value:
  2561. @example
  2562. (define (square x)
  2563. (mlet %state-monad ((count (current-state)))
  2564. (mbegin %state-monad
  2565. (set-current-state (+ 1 count))
  2566. (return (* x x)))))
  2567. (run-with-state (sequence %state-monad (map square (iota 3))) 0)
  2568. @result{} (0 1 4)
  2569. @result{} 3
  2570. @end example
  2571. When ``run'' through @var{%state-monad}, we obtain that additional state
  2572. value, which is the number of @code{square} calls.
  2573. @end defvr
  2574. @deffn {Monadic Procedure} current-state
  2575. Return the current state as a monadic value.
  2576. @end deffn
  2577. @deffn {Monadic Procedure} set-current-state @var{value}
  2578. Set the current state to @var{value} and return the previous state as a
  2579. monadic value.
  2580. @end deffn
  2581. @deffn {Monadic Procedure} state-push @var{value}
  2582. Push @var{value} to the current state, which is assumed to be a list,
  2583. and return the previous state as a monadic value.
  2584. @end deffn
  2585. @deffn {Monadic Procedure} state-pop
  2586. Pop a value from the current state and return it as a monadic value.
  2587. The state is assumed to be a list.
  2588. @end deffn
  2589. @deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}]
  2590. Run monadic value @var{mval} starting with @var{state} as the initial
  2591. state. Return two values: the resulting value, and the resulting state.
  2592. @end deffn
  2593. The main interface to the store monad, provided by the @code{(guix
  2594. store)} module, is as follows.
  2595. @defvr {Scheme Variable} %store-monad
  2596. The store monad---an alias for @var{%state-monad}.
  2597. Values in the store monad encapsulate accesses to the store. When its
  2598. effect is needed, a value of the store monad must be ``evaluated'' by
  2599. passing it to the @code{run-with-store} procedure (see below.)
  2600. @end defvr
  2601. @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
  2602. Run @var{mval}, a monadic value in the store monad, in @var{store}, an
  2603. open store connection.
  2604. @end deffn
  2605. @deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}]
  2606. Return as a monadic value the absolute file name in the store of the file
  2607. containing @var{text}, a string. @var{references} is a list of store items that the
  2608. resulting text file refers to; it defaults to the empty list.
  2609. @end deffn
  2610. @deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
  2611. [#:recursive? #t]
  2612. Return the name of @var{file} once interned in the store. Use
  2613. @var{name} as its store name, or the basename of @var{file} if
  2614. @var{name} is omitted.
  2615. When @var{recursive?} is true, the contents of @var{file} are added
  2616. recursively; if @var{file} designates a flat file and @var{recursive?}
  2617. is true, its contents are added, and its permission bits are kept.
  2618. The example below adds a file to the store, under two different names:
  2619. @example
  2620. (run-with-store (open-connection)
  2621. (mlet %store-monad ((a (interned-file "README"))
  2622. (b (interned-file "README" "LEGU-MIN")))
  2623. (return (list a b))))
  2624. @result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
  2625. @end example
  2626. @end deffn
  2627. The @code{(guix packages)} module exports the following package-related
  2628. monadic procedures:
  2629. @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
  2630. [#:system (%current-system)] [#:target #f] @
  2631. [#:output "out"] Return as a monadic
  2632. value in the absolute file name of @var{file} within the @var{output}
  2633. directory of @var{package}. When @var{file} is omitted, return the name
  2634. of the @var{output} directory of @var{package}. When @var{target} is
  2635. true, use it as a cross-compilation target triplet.
  2636. @end deffn
  2637. @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
  2638. @deffnx {Monadic Procedure} package->cross-derivation @var{package} @
  2639. @var{target} [@var{system}]
  2640. Monadic version of @code{package-derivation} and
  2641. @code{package-cross-derivation} (@pxref{Defining Packages}).
  2642. @end deffn
  2643. @node G-Expressions
  2644. @section G-Expressions
  2645. @cindex G-expression
  2646. @cindex build code quoting
  2647. So we have ``derivations'', which represent a sequence of build actions
  2648. to be performed to produce an item in the store (@pxref{Derivations}).
  2649. Those build actions are performed when asking the daemon to actually
  2650. build the derivations; they are run by the daemon in a container
  2651. (@pxref{Invoking guix-daemon}).
  2652. @cindex strata of code
  2653. It should come as no surprise that we like to write those build actions
  2654. in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
  2655. code@footnote{The term @dfn{stratum} in this context was coined by
  2656. Manuel Serrano et al.@: in the context of their work on Hop. Oleg
  2657. Kiselyov, who has written insightful
  2658. @url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
  2659. on this topic}, refers to this kind of code generation as
  2660. @dfn{staging}.}: the ``host code''---code that defines packages, talks
  2661. to the daemon, etc.---and the ``build code''---code that actually
  2662. performs build actions, such as making directories, invoking
  2663. @command{make}, etc.
  2664. To describe a derivation and its build actions, one typically needs to
  2665. embed build code inside host code. It boils down to manipulating build
  2666. code as data, and Scheme's homoiconicity---code has a direct
  2667. representation as data---comes in handy for that. But we need more than
  2668. Scheme's normal @code{quasiquote} mechanism to construct build
  2669. expressions.
  2670. The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
  2671. S-expressions adapted to build expressions. G-expressions, or
  2672. @dfn{gexps}, consist essentially in three syntactic forms: @code{gexp},
  2673. @code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
  2674. @code{#$}, and @code{#$@@}), which are comparable respectively to
  2675. @code{quasiquote}, @code{unquote}, and @code{unquote-splicing}
  2676. (@pxref{Expression Syntax, @code{quasiquote},, guile, GNU Guile
  2677. Reference Manual}). However, there are major differences:
  2678. @itemize
  2679. @item
  2680. Gexps are meant to be written to a file and run or manipulated by other
  2681. processes.
  2682. @item
  2683. When a high-level object such as a package or derivation is unquoted
  2684. inside a gexp, the result is as if its output file name had been
  2685. introduced.
  2686. @item
  2687. Gexps carry information about the packages or derivations they refer to,
  2688. and these dependencies are automatically added as inputs to the build
  2689. processes that use them.
  2690. @end itemize
  2691. @cindex lowering, of high-level objects in gexps
  2692. This mechanism is not limited to package and derivation
  2693. objects: @dfn{compilers} able to ``lower'' other high-level objects to
  2694. derivations or files in the store can be defined,
  2695. such that these objects can also be inserted
  2696. into gexps. For example, a useful type of high-level object that can be
  2697. inserted in a gexp is ``file-like objects'', which make it easy to
  2698. add files to the store and refer to them in
  2699. derivations and such (see @code{local-file} and @code{plain-file}
  2700. below.)
  2701. To illustrate the idea, here is an example of a gexp:
  2702. @example
  2703. (define build-exp
  2704. #~(begin
  2705. (mkdir #$output)
  2706. (chdir #$output)
  2707. (symlink (string-append #$coreutils "/bin/ls")
  2708. "list-files")))
  2709. @end example
  2710. This gexp can be passed to @code{gexp->derivation}; we obtain a
  2711. derivation that builds a directory containing exactly one symlink to
  2712. @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
  2713. @example
  2714. (gexp->derivation "the-thing" build-exp)
  2715. @end example
  2716. As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
  2717. substituted to the reference to the @var{coreutils} package in the
  2718. actual build code, and @var{coreutils} is automatically made an input to
  2719. the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
  2720. output)}) is replaced by a string containing the derivation's output
  2721. directory name.
  2722. @cindex cross compilation
  2723. In a cross-compilation context, it is useful to distinguish between
  2724. references to the @emph{native} build of a package---that can run on the
  2725. host---versus references to cross builds of a package. To that end, the
  2726. @code{#+} plays the same role as @code{#$}, but is a reference to a
  2727. native package build:
  2728. @example
  2729. (gexp->derivation "vi"
  2730. #~(begin
  2731. (mkdir #$output)
  2732. (system* (string-append #+coreutils "/bin/ln")
  2733. "-s"
  2734. (string-append #$emacs "/bin/emacs")
  2735. (string-append #$output "/bin/vi")))
  2736. #:target "mips64el-linux")
  2737. @end example
  2738. @noindent
  2739. In the example above, the native build of @var{coreutils} is used, so
  2740. that @command{ln} can actually run on the host; but then the
  2741. cross-compiled build of @var{emacs} is referenced.
  2742. The syntactic form to construct gexps is summarized below.
  2743. @deffn {Scheme Syntax} #~@var{exp}
  2744. @deffnx {Scheme Syntax} (gexp @var{exp})
  2745. Return a G-expression containing @var{exp}. @var{exp} may contain one
  2746. or more of the following forms:
  2747. @table @code
  2748. @item #$@var{obj}
  2749. @itemx (ungexp @var{obj})
  2750. Introduce a reference to @var{obj}. @var{obj} may have one of the
  2751. supported types, for example a package or a
  2752. derivation, in which case the @code{ungexp} form is replaced by its
  2753. output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
  2754. If @var{obj} is a list, it is traversed and references to supported
  2755. objects are substituted similarly.
  2756. If @var{obj} is another gexp, its contents are inserted and its
  2757. dependencies are added to those of the containing gexp.
  2758. If @var{obj} is another kind of object, it is inserted as is.
  2759. @item #$@var{obj}:@var{output}
  2760. @itemx (ungexp @var{obj} @var{output})
  2761. This is like the form above, but referring explicitly to the
  2762. @var{output} of @var{obj}---this is useful when @var{obj} produces
  2763. multiple outputs (@pxref{Packages with Multiple Outputs}).
  2764. @item #+@var{obj}
  2765. @itemx #+@var{obj}:output
  2766. @itemx (ungexp-native @var{obj})
  2767. @itemx (ungexp-native @var{obj} @var{output})
  2768. Same as @code{ungexp}, but produces a reference to the @emph{native}
  2769. build of @var{obj} when used in a cross compilation context.
  2770. @item #$output[:@var{output}]
  2771. @itemx (ungexp output [@var{output}])
  2772. Insert a reference to derivation output @var{output}, or to the main
  2773. output when @var{output} is omitted.
  2774. This only makes sense for gexps passed to @code{gexp->derivation}.
  2775. @item #$@@@var{lst}
  2776. @itemx (ungexp-splicing @var{lst})
  2777. Like the above, but splices the contents of @var{lst} inside the
  2778. containing list.
  2779. @item #+@@@var{lst}
  2780. @itemx (ungexp-native-splicing @var{lst})
  2781. Like the above, but refers to native builds of the objects listed in
  2782. @var{lst}.
  2783. @end table
  2784. G-expressions created by @code{gexp} or @code{#~} are run-time objects
  2785. of the @code{gexp?} type (see below.)
  2786. @end deffn
  2787. @deffn {Scheme Procedure} gexp? @var{obj}
  2788. Return @code{#t} if @var{obj} is a G-expression.
  2789. @end deffn
  2790. G-expressions are meant to be written to disk, either as code building
  2791. some derivation, or as plain files in the store. The monadic procedures
  2792. below allow you to do that (@pxref{The Store Monad}, for more
  2793. information about monads.)
  2794. @deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
  2795. [#:system (%current-system)] [#:target #f] [#:graft? #t] @
  2796. [#:hash #f] [#:hash-algo #f] @
  2797. [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
  2798. [#:module-path @var{%load-path}] @
  2799. [#:references-graphs #f] [#:allowed-references #f] @
  2800. [#:leaked-env-vars #f] @
  2801. [#:script-name (string-append @var{name} "-builder")] @
  2802. [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f]
  2803. Return a derivation @var{name} that runs @var{exp} (a gexp) with
  2804. @var{guile-for-build} (a derivation) on @var{system}; @var{exp} is
  2805. stored in a file called @var{script-name}. When @var{target} is true,
  2806. it is used as the cross-compilation target triplet for packages referred
  2807. to by @var{exp}.
  2808. Make @var{modules} available in the evaluation context of @var{exp};
  2809. @var{modules} is a list of names of Guile modules searched in
  2810. @var{module-path} to be copied in the store, compiled, and made available in
  2811. the load path during the execution of @var{exp}---e.g., @code{((guix
  2812. build utils) (guix build gnu-build-system))}.
  2813. @var{graft?} determines whether packages referred to by @var{exp} should be grafted when
  2814. applicable.
  2815. When @var{references-graphs} is true, it must be a list of tuples of one of the
  2816. following forms:
  2817. @example
  2818. (@var{file-name} @var{package})
  2819. (@var{file-name} @var{package} @var{output})
  2820. (@var{file-name} @var{derivation})
  2821. (@var{file-name} @var{derivation} @var{output})
  2822. (@var{file-name} @var{store-item})
  2823. @end example
  2824. The right-hand-side of each element of @var{references-graphs} is automatically made
  2825. an input of the build process of @var{exp}. In the build environment, each
  2826. @var{file-name} contains the reference graph of the corresponding item, in a simple
  2827. text format.
  2828. @var{allowed-references} must be either @code{#f} or a list of output names and packages.
  2829. In the latter case, the list denotes store items that the result is allowed to
  2830. refer to. Any reference to another store item will lead to a build error.
  2831. The other arguments are as for @code{derivation} (@pxref{Derivations}).
  2832. @end deffn
  2833. @cindex file-like objects
  2834. The @code{local-file}, @code{plain-file}, @code{computed-file},
  2835. @code{program-file}, and @code{scheme-file} procedures below return
  2836. @dfn{file-like objects}. That is, when unquoted in a G-expression,
  2837. these objects lead to a file in the store. Consider this G-expression:
  2838. @example
  2839. #~(system* (string-append #$glibc "/sbin/nscd") "-f"
  2840. #$(local-file "/tmp/my-nscd.conf"))
  2841. @end example
  2842. The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it
  2843. to the store. Once expanded, for instance @i{via}
  2844. @code{gexp->derivation}, the G-expression refers to that copy under
  2845. @file{/gnu/store}; thus, modifying or removing the file in @file{/tmp}
  2846. does not have any effect on what the G-expression does.
  2847. @code{plain-file} can be used similarly; it differs in that the file
  2848. content is directly passed as a string.
  2849. @deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
  2850. [#:recursive? #t]
  2851. Return an object representing local file @var{file} to add to the store; this
  2852. object can be used in a gexp. If @var{file} is a relative file name, it is looked
  2853. up relative to the source file where this form appears. @var{file} will be added to
  2854. the store under @var{name}--by default the base name of @var{file}.
  2855. When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file}
  2856. designates a flat file and @var{recursive?} is true, its contents are added, and its
  2857. permission bits are kept.
  2858. This is the declarative counterpart of the @code{interned-file} monadic
  2859. procedure (@pxref{The Store Monad, @code{interned-file}}).
  2860. @end deffn
  2861. @deffn {Scheme Procedure} plain-file @var{name} @var{content}
  2862. Return an object representing a text file called @var{name} with the given
  2863. @var{content} (a string) to be added to the store.
  2864. This is the declarative counterpart of @code{text-file}.
  2865. @end deffn
  2866. @deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @
  2867. [#:modules '()] [#:options '(#:local-build? #t)]
  2868. Return an object representing the store item @var{name}, a file or
  2869. directory computed by @var{gexp}. @var{modules} specifies the set of
  2870. modules visible in the execution context of @var{gexp}. @var{options}
  2871. is a list of additional arguments to pass to @code{gexp->derivation}.
  2872. This is the declarative counterpart of @code{gexp->derivation}.
  2873. @end deffn
  2874. @deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
  2875. Return an executable script @var{name} that runs @var{exp} using
  2876. @var{guile} with @var{modules} in its search path.
  2877. The example below builds a script that simply invokes the @command{ls}
  2878. command:
  2879. @example
  2880. (use-modules (guix gexp) (gnu packages base))
  2881. (gexp->script "list-files"
  2882. #~(execl (string-append #$coreutils "/bin/ls")
  2883. "ls"))
  2884. @end example
  2885. When ``running'' it through the store (@pxref{The Store Monad,
  2886. @code{run-with-store}}), we obtain a derivation that produces an
  2887. executable file @file{/gnu/store/@dots{}-list-files} along these lines:
  2888. @example
  2889. #!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
  2890. !#
  2891. (execl (string-append "/gnu/store/@dots{}-coreutils-8.22"/bin/ls")
  2892. "ls")
  2893. @end example
  2894. @end deffn
  2895. @deffn {Scheme Procedure} program-file @var{name} @var{exp} @
  2896. [#:modules '()] [#:guile #f]
  2897. Return an object representing the executable store item @var{name} that
  2898. runs @var{gexp}. @var{guile} is the Guile package used to execute that
  2899. script, and @var{modules} is the list of modules visible to that script.
  2900. This is the declarative counterpart of @code{gexp->script}.
  2901. @end deffn
  2902. @deffn {Monadic Procedure} gexp->file @var{name} @var{exp}
  2903. Return a derivation that builds a file @var{name} containing @var{exp}.
  2904. The resulting file holds references to all the dependencies of @var{exp}
  2905. or a subset thereof.
  2906. @end deffn
  2907. @deffn {Scheme Procedure} scheme-file @var{name} @var{exp}
  2908. Return an object representing the Scheme file @var{name} that contains
  2909. @var{exp}.
  2910. This is the declarative counterpart of @code{gexp->file}.
  2911. @end deffn
  2912. @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
  2913. Return as a monadic value a derivation that builds a text file
  2914. containing all of @var{text}. @var{text} may list, in addition to
  2915. strings, objects of any type that can be used in a gexp: packages,
  2916. derivations, local file objects, etc. The resulting store file holds
  2917. references to all these.
  2918. This variant should be preferred over @code{text-file} anytime the file
  2919. to create will reference items from the store. This is typically the
  2920. case when building a configuration file that embeds store file names,
  2921. like this:
  2922. @example
  2923. (define (profile.sh)
  2924. ;; Return the name of a shell script in the store that
  2925. ;; initializes the 'PATH' environment variable.
  2926. (text-file* "profile.sh"
  2927. "export PATH=" coreutils "/bin:"
  2928. grep "/bin:" sed "/bin\n"))
  2929. @end example
  2930. In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
  2931. will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
  2932. preventing them from being garbage-collected during its lifetime.
  2933. @end deffn
  2934. @deffn {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{}
  2935. Return an object representing store file @var{name} containing
  2936. @var{text}. @var{text} is a sequence of strings and file-like objects,
  2937. as in:
  2938. @example
  2939. (mixed-text-file "profile"
  2940. "export PATH=" coreutils "/bin:" grep "/bin")
  2941. @end example
  2942. This is the declarative counterpart of @code{text-file*}.
  2943. @end deffn
  2944. Of course, in addition to gexps embedded in ``host'' code, there are
  2945. also modules containing build tools. To make it clear that they are
  2946. meant to be used in the build stratum, these modules are kept in the
  2947. @code{(guix build @dots{})} name space.
  2948. @cindex lowering, of high-level objects in gexps
  2949. Internally, high-level objects are @dfn{lowered}, using their compiler,
  2950. to either derivations or store items. For instance, lowering a package
  2951. yields a derivation, and lowering a @code{plain-file} yields a store
  2952. item. This is achieved using the @code{lower-object} monadic procedure.
  2953. @deffn {Monadic Procedure} lower-object @var{obj} [@var{system}] @
  2954. [#:target #f]
  2955. Return as a value in @var{%store-monad} the derivation or store item
  2956. corresponding to @var{obj} for @var{system}, cross-compiling for
  2957. @var{target} if @var{target} is true. @var{obj} must be an object that
  2958. has an associated gexp compiler, such as a @code{<package>}.
  2959. @end deffn
  2960. @c *********************************************************************
  2961. @node Utilities
  2962. @chapter Utilities
  2963. This section describes tools primarily targeted at developers and users
  2964. who write new package definitions. They complement the Scheme
  2965. programming interface of Guix in a convenient way.
  2966. @menu
  2967. * Invoking guix build:: Building packages from the command line.
  2968. * Invoking guix edit:: Editing package definitions.
  2969. * Invoking guix download:: Downloading a file and printing its hash.
  2970. * Invoking guix hash:: Computing the cryptographic hash of a file.
  2971. * Invoking guix import:: Importing package definitions.
  2972. * Invoking guix refresh:: Updating package definitions.
  2973. * Invoking guix lint:: Finding errors in package definitions.
  2974. * Invoking guix size:: Profiling disk usage.
  2975. * Invoking guix graph:: Visualizing the graph of packages.
  2976. * Invoking guix environment:: Setting up development environments.
  2977. * Invoking guix publish:: Sharing substitutes.
  2978. * Invoking guix challenge:: Challenging substitute servers.
  2979. * Invoking guix container:: Process isolation.
  2980. @end menu
  2981. @node Invoking guix build
  2982. @section Invoking @command{guix build}
  2983. The @command{guix build} command builds packages or derivations and
  2984. their dependencies, and prints the resulting store paths. Note that it
  2985. does not modify the user's profile---this is the job of the
  2986. @command{guix package} command (@pxref{Invoking guix package}). Thus,
  2987. it is mainly useful for distribution developers.
  2988. The general syntax is:
  2989. @example
  2990. guix build @var{options} @var{package-or-derivation}@dots{}
  2991. @end example
  2992. @var{package-or-derivation} may be either the name of a package found in
  2993. the software distribution such as @code{coreutils} or
  2994. @code{coreutils-8.20}, or a derivation such as
  2995. @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
  2996. package with the corresponding name (and optionally version) is searched
  2997. for among the GNU distribution modules (@pxref{Package Modules}).
  2998. Alternatively, the @code{--expression} option may be used to specify a
  2999. Scheme expression that evaluates to a package; this is useful when
  3000. disambiguation among several same-named packages or package variants is
  3001. needed.
  3002. The @var{options} may be zero or more of the following:
  3003. @table @code
  3004. @item --file=@var{file}
  3005. @itemx -f @var{file}
  3006. Build the package or derivation that the code within @var{file}
  3007. evaluates to.
  3008. As an example, @var{file} might contain a package definition like this
  3009. (@pxref{Defining Packages}):
  3010. @example
  3011. @verbatiminclude package-hello.scm
  3012. @end example
  3013. @item --expression=@var{expr}
  3014. @itemx -e @var{expr}
  3015. Build the package or derivation @var{expr} evaluates to.
  3016. For example, @var{expr} may be @code{(@@ (gnu packages guile)
  3017. guile-1.8)}, which unambiguously designates this specific variant of
  3018. version 1.8 of Guile.
  3019. Alternately, @var{expr} may be a G-expression, in which case it is used
  3020. as a build program passed to @code{gexp->derivation}
  3021. (@pxref{G-Expressions}).
  3022. Lastly, @var{expr} may refer to a zero-argument monadic procedure
  3023. (@pxref{The Store Monad}). The procedure must return a derivation as a
  3024. monadic value, which is then passed through @code{run-with-store}.
  3025. @item --source
  3026. @itemx -S
  3027. Build the packages' source derivations, rather than the packages
  3028. themselves.
  3029. For instance, @code{guix build -S gcc} returns something like
  3030. @file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
  3031. The returned source tarball is the result of applying any patches and
  3032. code snippets specified in the package's @code{origin} (@pxref{Defining
  3033. Packages}).
  3034. @item --sources
  3035. Fetch and return the source of @var{package-or-derivation} and all their
  3036. dependencies, recursively. This is a handy way to obtain a local copy
  3037. of all the source code needed to build @var{packages}, allowing you to
  3038. eventually build them even without network access. It is an extension
  3039. of the @code{--source} option and can accept one of the following
  3040. optional argument values:
  3041. @table @code
  3042. @item package
  3043. This value causes the @code{--sources} option to behave in the same way
  3044. as the @code{--source} option.
  3045. @item all
  3046. Build all packages' source derivations, including any source that might
  3047. be listed as @code{inputs}. This is the default value.
  3048. @example
  3049. $ guix build --sources tzdata
  3050. The following derivations will be built:
  3051. /gnu/store/@dots{}-tzdata2015b.tar.gz.drv
  3052. /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
  3053. @end example
  3054. @item transitive
  3055. Build all packages' source derivations, as well as all source
  3056. derivations for packages' transitive inputs. This can be used e.g. to
  3057. prefetch package source for later offline building.
  3058. @example
  3059. $ guix build --sources=transitive tzdata
  3060. The following derivations will be built:
  3061. /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
  3062. /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv
  3063. /gnu/store/@dots{}-grep-2.21.tar.xz.drv
  3064. /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv
  3065. /gnu/store/@dots{}-make-4.1.tar.xz.drv
  3066. /gnu/store/@dots{}-bash-4.3.tar.xz.drv
  3067. @dots{}
  3068. @end example
  3069. @end table
  3070. @item --system=@var{system}
  3071. @itemx -s @var{system}
  3072. Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
  3073. the host's system type.
  3074. An example use of this is on Linux-based systems, which can emulate
  3075. different personalities. For instance, passing
  3076. @code{--system=i686-linux} on an @code{x86_64-linux} system allows users
  3077. to build packages in a complete 32-bit environment.
  3078. @item --target=@var{triplet}
  3079. @cindex cross-compilation
  3080. Cross-build for @var{triplet}, which must be a valid GNU triplet, such
  3081. as @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU
  3082. configuration triplets,, configure, GNU Configure and Build System}).
  3083. @item --with-source=@var{source}
  3084. Use @var{source} as the source of the corresponding package.
  3085. @var{source} must be a file name or a URL, as for @command{guix
  3086. download} (@pxref{Invoking guix download}).
  3087. The ``corresponding package'' is taken to be one specified on the
  3088. command line whose name matches the base of @var{source}---e.g., if
  3089. @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
  3090. package is @code{guile}. Likewise, the version string is inferred from
  3091. @var{source}; in the previous example, it's @code{2.0.10}.
  3092. This option allows users to try out versions of packages other than the
  3093. one provided by the distribution. The example below downloads
  3094. @file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
  3095. the @code{ed} package:
  3096. @example
  3097. guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
  3098. @end example
  3099. As a developer, @code{--with-source} makes it easy to test release
  3100. candidates:
  3101. @example
  3102. guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
  3103. @end example
  3104. @dots{} or to build from a checkout in a pristine environment:
  3105. @example
  3106. $ git clone git://git.sv.gnu.org/guix.git
  3107. $ guix build guix --with-source=./guix
  3108. @end example
  3109. @anchor{build-check}
  3110. @item --check
  3111. @cindex determinism, checking
  3112. @cindex reproducibility, checking
  3113. Rebuild @var{package-or-derivation}, which are already available in the
  3114. store, and raise an error if the build results are not bit-for-bit
  3115. identical.
  3116. This mechanism allows you to check whether previously-installed
  3117. substitutes are genuine (@pxref{Substitutes}), or whether a package's
  3118. build result is deterministic. @xref{Invoking guix challenge}, for more
  3119. background information and tools.
  3120. @item --no-grafts
  3121. Do not ``graft'' packages. In practice, this means that package updates
  3122. available as grafts are not applied. @xref{Security Updates}, for more
  3123. information on grafts.
  3124. @item --derivations
  3125. @itemx -d
  3126. Return the derivation paths, not the output paths, of the given
  3127. packages.
  3128. @item --root=@var{file}
  3129. @itemx -r @var{file}
  3130. Make @var{file} a symlink to the result, and register it as a garbage
  3131. collector root.
  3132. @item --log-file
  3133. Return the build log file names or URLs for the given
  3134. @var{package-or-derivation}s, or raise an error if build logs are
  3135. missing.
  3136. This works regardless of how packages or derivations are specified. For
  3137. instance, the following invocations are equivalent:
  3138. @example
  3139. guix build --log-file `guix build -d guile`
  3140. guix build --log-file `guix build guile`
  3141. guix build --log-file guile
  3142. guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
  3143. @end example
  3144. If a log is unavailable locally, and unless @code{--no-substitutes} is
  3145. passed, the command looks for a corresponding log on one of the
  3146. substitute servers (as specified with @code{--substitute-urls}.)
  3147. So for instance, let's say you want to see the build log of GDB on MIPS
  3148. but you're actually on an @code{x86_64} machine:
  3149. @example
  3150. $ guix build --log-file gdb -s mips64el-linux
  3151. http://hydra.gnu.org/log/@dots{}-gdb-7.10
  3152. @end example
  3153. You can freely access a huge library of build logs!
  3154. @end table
  3155. @cindex common build options
  3156. In addition, a number of options that control the build process are
  3157. common to @command{guix build} and other commands that can spawn builds,
  3158. such as @command{guix package} or @command{guix archive}. These are the
  3159. following:
  3160. @table @code
  3161. @item --load-path=@var{directory}
  3162. @itemx -L @var{directory}
  3163. Add @var{directory} to the front of the package module search path
  3164. (@pxref{Package Modules}).
  3165. This allows users to define their own packages and make them visible to
  3166. the command-line tools.
  3167. @item --keep-failed
  3168. @itemx -K
  3169. Keep the build tree of failed builds. Thus, if a build fail, its build
  3170. tree is kept under @file{/tmp}, in a directory whose name is shown at
  3171. the end of the build log. This is useful when debugging build issues.
  3172. @item --dry-run
  3173. @itemx -n
  3174. Do not build the derivations.
  3175. @item --fallback
  3176. When substituting a pre-built binary fails, fall back to building
  3177. packages locally.
  3178. @item --substitute-urls=@var{urls}
  3179. @anchor{client-substitute-urls}
  3180. Consider @var{urls} the whitespace-separated list of substitute source
  3181. URLs, overriding the default list of URLs of @command{guix-daemon}
  3182. (@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}).
  3183. This means that substitutes may be downloaded from @var{urls}, provided
  3184. they are signed by a key authorized by the system administrator
  3185. (@pxref{Substitutes}).
  3186. @item --no-substitutes
  3187. Do not use substitutes for build products. That is, always build things
  3188. locally instead of allowing downloads of pre-built binaries
  3189. (@pxref{Substitutes}).
  3190. @item --rounds=@var{n}
  3191. Build each derivation @var{n} times in a row, and raise an error if
  3192. consecutive build results are not bit-for-bit identical.
  3193. This is a useful way to detect non-deterministic builds processes.
  3194. Non-deterministic build processes are a problem because they make it
  3195. practically impossible for users to @emph{verify} whether third-party
  3196. binaries are genuine. @xref{Invoking guix challenge}, for more.
  3197. Note that, currently, the differing build results are not kept around,
  3198. so you will have to manually investigate in case of an error---e.g., by
  3199. stashing one of the build results with @code{guix archive --export},
  3200. then rebuilding, and finally comparing the two results.
  3201. @item --no-build-hook
  3202. Do not attempt to offload builds @i{via} the daemon's ``build hook''
  3203. (@pxref{Daemon Offload Setup}). That is, always build things locally
  3204. instead of offloading builds to remote machines.
  3205. @item --max-silent-time=@var{seconds}
  3206. When the build or substitution process remains silent for more than
  3207. @var{seconds}, terminate it and report a build failure.
  3208. @item --timeout=@var{seconds}
  3209. Likewise, when the build or substitution process lasts for more than
  3210. @var{seconds}, terminate it and report a build failure.
  3211. By default there is no timeout. This behavior can be restored with
  3212. @code{--timeout=0}.
  3213. @item --verbosity=@var{level}
  3214. Use the given verbosity level. @var{level} must be an integer between 0
  3215. and 5; higher means more verbose output. Setting a level of 4 or more
  3216. may be helpful when debugging setup issues with the build daemon.
  3217. @item --cores=@var{n}
  3218. @itemx -c @var{n}
  3219. Allow the use of up to @var{n} CPU cores for the build. The special
  3220. value @code{0} means to use as many CPU cores as available.
  3221. @item --max-jobs=@var{n}
  3222. @itemx -M @var{n}
  3223. Allow at most @var{n} build jobs in parallel. @xref{Invoking
  3224. guix-daemon, @code{--max-jobs}}, for details about this option and the
  3225. equivalent @command{guix-daemon} option.
  3226. @end table
  3227. Behind the scenes, @command{guix build} is essentially an interface to
  3228. the @code{package-derivation} procedure of the @code{(guix packages)}
  3229. module, and to the @code{build-derivations} procedure of the @code{(guix
  3230. derivations)} module.
  3231. In addition to options explicitly passed on the command line,
  3232. @command{guix build} and other @command{guix} commands that support
  3233. building honor the @code{GUIX_BUILD_OPTIONS} environment variable.
  3234. @defvr {Environment Variable} GUIX_BUILD_OPTIONS
  3235. Users can define this variable to a list of command line options that
  3236. will automatically be used by @command{guix build} and other
  3237. @command{guix} commands that can perform builds, as in the example
  3238. below:
  3239. @example
  3240. $ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
  3241. @end example
  3242. These options are parsed independently, and the result is appended to
  3243. the parsed command-line options.
  3244. @end defvr
  3245. @node Invoking guix edit
  3246. @section Invoking @command{guix edit}
  3247. @cindex package definition, editing
  3248. So many packages, so many source files! The @command{guix edit} command
  3249. facilitates the life of packagers by pointing their editor at the source
  3250. file containing the definition of the specified packages. For instance:
  3251. @example
  3252. guix edit gcc-4.8 vim
  3253. @end example
  3254. @noindent
  3255. launches the program specified in the @code{VISUAL} or in the
  3256. @code{EDITOR} environment variable to edit the recipe of GCC@tie{}4.8.4
  3257. and that of Vim.
  3258. If you are using Emacs, note that the Emacs user interface provides
  3259. similar functionality in the ``package info'' and ``package list''
  3260. buffers created by @kbd{M-x guix-search-by-name} and similar commands
  3261. (@pxref{Emacs Commands}).
  3262. @node Invoking guix download
  3263. @section Invoking @command{guix download}
  3264. When writing a package definition, developers typically need to download
  3265. the package's source tarball, compute its SHA256 hash, and write that
  3266. hash in the package definition (@pxref{Defining Packages}). The
  3267. @command{guix download} tool helps with this task: it downloads a file
  3268. from the given URI, adds it to the store, and prints both its file name
  3269. in the store and its SHA256 hash.
  3270. The fact that the downloaded file is added to the store saves bandwidth:
  3271. when the developer eventually tries to build the newly defined package
  3272. with @command{guix build}, the source tarball will not have to be
  3273. downloaded again because it is already in the store. It is also a
  3274. convenient way to temporarily stash files, which may be deleted
  3275. eventually (@pxref{Invoking guix gc}).
  3276. The @command{guix download} command supports the same URIs as used in
  3277. package definitions. In particular, it supports @code{mirror://} URIs.
  3278. @code{https} URIs (HTTP over TLS) are supported @emph{provided} the
  3279. Guile bindings for GnuTLS are available in the user's environment; when
  3280. they are not available, an error is raised. @xref{Guile Preparations,
  3281. how to install the GnuTLS bindings for Guile,, gnutls-guile,
  3282. GnuTLS-Guile}, for more information.
  3283. The following option is available:
  3284. @table @code
  3285. @item --format=@var{fmt}
  3286. @itemx -f @var{fmt}
  3287. Write the hash in the format specified by @var{fmt}. For more
  3288. information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
  3289. @end table
  3290. @node Invoking guix hash
  3291. @section Invoking @command{guix hash}
  3292. The @command{guix hash} command computes the SHA256 hash of a file.
  3293. It is primarily a convenience tool for anyone contributing to the
  3294. distribution: it computes the cryptographic hash of a file, which can be
  3295. used in the definition of a package (@pxref{Defining Packages}).
  3296. The general syntax is:
  3297. @example
  3298. guix hash @var{option} @var{file}
  3299. @end example
  3300. @command{guix hash} has the following option:
  3301. @table @code
  3302. @item --format=@var{fmt}
  3303. @itemx -f @var{fmt}
  3304. Write the hash in the format specified by @var{fmt}.
  3305. Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
  3306. (@code{hex} and @code{hexadecimal} can be used as well).
  3307. If the @option{--format} option is not specified, @command{guix hash}
  3308. will output the hash in @code{nix-base32}. This representation is used
  3309. in the definitions of packages.
  3310. @item --recursive
  3311. @itemx -r
  3312. Compute the hash on @var{file} recursively.
  3313. In this case, the hash is computed on an archive containing @var{file},
  3314. including its children if it is a directory. Some of @var{file}'s
  3315. meta-data is part of the archive; for instance, when @var{file} is a
  3316. regular file, the hash is different depending on whether @var{file} is
  3317. executable or not. Meta-data such as time stamps has no impact on the
  3318. hash (@pxref{Invoking guix archive}).
  3319. @c FIXME: Replace xref above with xref to an ``Archive'' section when
  3320. @c it exists.
  3321. @end table
  3322. @node Invoking guix import
  3323. @section Invoking @command{guix import}
  3324. @cindex importing packages
  3325. @cindex package import
  3326. @cindex package conversion
  3327. The @command{guix import} command is useful for people willing to add a
  3328. package to the distribution but who'd rather do as little work as
  3329. possible to get there---a legitimate demand. The command knows of a few
  3330. repositories from which it can ``import'' package meta-data. The result
  3331. is a package definition, or a template thereof, in the format we know
  3332. (@pxref{Defining Packages}).
  3333. The general syntax is:
  3334. @example
  3335. guix import @var{importer} @var{options}@dots{}
  3336. @end example
  3337. @var{importer} specifies the source from which to import package
  3338. meta-data, and @var{options} specifies a package identifier and other
  3339. options specific to @var{importer}. Currently, the available
  3340. ``importers'' are:
  3341. @table @code
  3342. @item gnu
  3343. Import meta-data for the given GNU package. This provides a template
  3344. for the latest version of that GNU package, including the hash of its
  3345. source tarball, and its canonical synopsis and description.
  3346. Additional information such as the package's dependencies and its
  3347. license needs to be figured out manually.
  3348. For example, the following command returns a package definition for
  3349. GNU@tie{}Hello:
  3350. @example
  3351. guix import gnu hello
  3352. @end example
  3353. Specific command-line options are:
  3354. @table @code
  3355. @item --key-download=@var{policy}
  3356. As for @code{guix refresh}, specify the policy to handle missing OpenPGP
  3357. keys when verifying the package's signature. @xref{Invoking guix
  3358. refresh, @code{--key-download}}.
  3359. @end table
  3360. @item pypi
  3361. @cindex pypi
  3362. Import meta-data from the @uref{https://pypi.python.org/, Python Package
  3363. Index}@footnote{This functionality requires Guile-JSON to be installed.
  3364. @xref{Requirements}.}. Information is taken from the JSON-formatted
  3365. description available at @code{pypi.python.org} and usually includes all
  3366. the relevant information, including package dependencies.
  3367. The command below imports meta-data for the @code{itsdangerous} Python
  3368. package:
  3369. @example
  3370. guix import pypi itsdangerous
  3371. @end example
  3372. @item gem
  3373. @cindex gem
  3374. Import meta-data from @uref{https://rubygems.org/,
  3375. RubyGems}@footnote{This functionality requires Guile-JSON to be
  3376. installed. @xref{Requirements}.}. Information is taken from the
  3377. JSON-formatted description available at @code{rubygems.org} and includes
  3378. most relevant information, including runtime dependencies. There are
  3379. some caveats, however. The meta-data doesn't distinguish between
  3380. synopses and descriptions, so the same string is used for both fields.
  3381. Additionally, the details of non-Ruby dependencies required to build
  3382. native extensions is unavailable and left as an exercise to the
  3383. packager.
  3384. The command below imports meta-data for the @code{rails} Ruby package:
  3385. @example
  3386. guix import gem rails
  3387. @end example
  3388. @item cpan
  3389. @cindex CPAN
  3390. Import meta-data from @uref{https://www.metacpan.org/, MetaCPAN}.
  3391. Information is taken from the JSON-formatted meta-data provided through
  3392. @uref{https://api.metacpan.org/, MetaCPAN's API} and includes most
  3393. relevant information, such as module dependencies. License information
  3394. should be checked closely. If Perl is available in the store, then the
  3395. @code{corelist} utility will be used to filter core modules out of the
  3396. list of dependencies.
  3397. The command command below imports meta-data for the @code{Acme::Boolean}
  3398. Perl module:
  3399. @example
  3400. guix import cpan Acme::Boolean
  3401. @end example
  3402. @item cran
  3403. @cindex CRAN
  3404. Import meta-data from @uref{http://cran.r-project.org/, CRAN}, the
  3405. central repository for the @uref{http://r-project.org, GNU@tie{}R
  3406. statistical and graphical environment}.
  3407. Information is extracted from the package's DESCRIPTION file.
  3408. The command command below imports meta-data for the @code{Cairo}
  3409. R package:
  3410. @example
  3411. guix import cran Cairo
  3412. @end example
  3413. @item nix
  3414. Import meta-data from a local copy of the source of the
  3415. @uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
  3416. relies on the @command{nix-instantiate} command of
  3417. @uref{http://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
  3418. typically written in a mixture of Nix-language and Bash code. This
  3419. command only imports the high-level package structure that is written in
  3420. the Nix language. It normally includes all the basic fields of a
  3421. package definition.
  3422. When importing a GNU package, the synopsis and descriptions are replaced
  3423. by their canonical upstream variant.
  3424. Usually, you will first need to do:
  3425. @example
  3426. export NIX_REMOTE=daemon
  3427. @end example
  3428. @noindent
  3429. so that @command{nix-instantiate} does not try to open the Nix database.
  3430. As an example, the command below imports the package definition of
  3431. LibreOffice (more precisely, it imports the definition of the package
  3432. bound to the @code{libreoffice} top-level attribute):
  3433. @example
  3434. guix import nix ~/path/to/nixpkgs libreoffice
  3435. @end example
  3436. @item hackage
  3437. @cindex hackage
  3438. Import meta-data from Haskell community's central package archive
  3439. @uref{https://hackage.haskell.org/, Hackage}. Information is taken from
  3440. Cabal files and includes all the relevant information, including package
  3441. dependencies.
  3442. Specific command-line options are:
  3443. @table @code
  3444. @item --stdin
  3445. @itemx -s
  3446. Read a Cabal file from the standard input.
  3447. @item --no-test-dependencies
  3448. @itemx -t
  3449. Do not include dependencies required by the test suites only.
  3450. @item --cabal-environment=@var{alist}
  3451. @itemx -e @var{alist}
  3452. @var{alist} is a Scheme alist defining the environment in which the
  3453. Cabal conditionals are evaluated. The accepted keys are: @code{os},
  3454. @code{arch}, @code{impl} and a string representing the name of a flag.
  3455. The value associated with a flag has to be either the symbol
  3456. @code{true} or @code{false}. The value associated with other keys
  3457. has to conform to the Cabal file format definition. The default value
  3458. associated with the keys @code{os}, @code{arch} and @code{impl} is
  3459. @samp{linux}, @samp{x86_64} and @samp{ghc} respectively.
  3460. @end table
  3461. The command below imports meta-data for the latest version of the
  3462. @code{HTTP} Haskell package without including test dependencies and
  3463. specifying the value of the flag @samp{network-uri} as @code{false}:
  3464. @example
  3465. guix import hackage -t -e "'((\"network-uri\" . false))" HTTP
  3466. @end example
  3467. A specific package version may optionally be specified by following the
  3468. package name by a hyphen and a version number as in the following example:
  3469. @example
  3470. guix import hackage mtl-2.1.3.1
  3471. @end example
  3472. @item elpa
  3473. @cindex elpa
  3474. Import meta-data from an Emacs Lisp Package Archive (ELPA) package
  3475. repository (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
  3476. Specific command-line options are:
  3477. @table @code
  3478. @item --archive=@var{repo}
  3479. @itemx -a @var{repo}
  3480. @var{repo} identifies the archive repository from which to retrieve the
  3481. information. Currently the supported repositories and their identifiers
  3482. are:
  3483. @itemize -
  3484. @item
  3485. @uref{http://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
  3486. identifier. This is the default.
  3487. @item
  3488. @uref{http://stable.melpa.org/packages, MELPA-Stable}, selected by the
  3489. @code{melpa-stable} identifier.
  3490. @item
  3491. @uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa}
  3492. identifier.
  3493. @end itemize
  3494. @end table
  3495. @end table
  3496. The structure of the @command{guix import} code is modular. It would be
  3497. useful to have more importers for other package formats, and your help
  3498. is welcome here (@pxref{Contributing}).
  3499. @node Invoking guix refresh
  3500. @section Invoking @command{guix refresh}
  3501. The primary audience of the @command{guix refresh} command is developers
  3502. of the GNU software distribution. By default, it reports any packages
  3503. provided by the distribution that are outdated compared to the latest
  3504. upstream version, like this:
  3505. @example
  3506. $ guix refresh
  3507. gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
  3508. gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
  3509. @end example
  3510. It does so by browsing each package's FTP directory and determining the
  3511. highest version number of the source tarballs therein. The command
  3512. knows how to update specific types of packages: GNU packages, ELPA
  3513. packages, etc.---see the documentation for @option{--type} below. The
  3514. are many packages, though, for which it lacks a method to determine
  3515. whether a new upstream release is available. However, the mechanism is
  3516. extensible, so feel free to get in touch with us to add a new method!
  3517. When passed @code{--update}, it modifies distribution source files to
  3518. update the version numbers and source tarball hashes of those packages'
  3519. recipes (@pxref{Defining Packages}). This is achieved by downloading
  3520. each package's latest source tarball and its associated OpenPGP
  3521. signature, authenticating the downloaded tarball against its signature
  3522. using @command{gpg}, and finally computing its hash. When the public
  3523. key used to sign the tarball is missing from the user's keyring, an
  3524. attempt is made to automatically retrieve it from a public key server;
  3525. when it's successful, the key is added to the user's keyring; otherwise,
  3526. @command{guix refresh} reports an error.
  3527. The following options are supported:
  3528. @table @code
  3529. @item --expression=@var{expr}
  3530. @itemx -e @var{expr}
  3531. Consider the package @var{expr} evaluates to.
  3532. This is useful to precisely refer to a package, as in this example:
  3533. @example
  3534. guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)'
  3535. @end example
  3536. This command lists the dependents of the ``final'' libc (essentially all
  3537. the packages.)
  3538. @item --update
  3539. @itemx -u
  3540. Update distribution source files (package recipes) in place. This is
  3541. usually run from a checkout of the Guix source tree (@pxref{Running
  3542. Guix Before It Is Installed}):
  3543. @example
  3544. $ ./pre-inst-env guix refresh -s non-core
  3545. @end example
  3546. @xref{Defining Packages}, for more information on package definitions.
  3547. @item --select=[@var{subset}]
  3548. @itemx -s @var{subset}
  3549. Select all the packages in @var{subset}, one of @code{core} or
  3550. @code{non-core}.
  3551. The @code{core} subset refers to all the packages at the core of the
  3552. distribution---i.e., packages that are used to build ``everything
  3553. else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
  3554. changing one of these packages in the distribution entails a rebuild of
  3555. all the others. Thus, such updates are an inconvenience to users in
  3556. terms of build time or bandwidth used to achieve the upgrade.
  3557. The @code{non-core} subset refers to the remaining packages. It is
  3558. typically useful in cases where an update of the core packages would be
  3559. inconvenient.
  3560. @item --type=@var{updater}
  3561. @itemx -t @var{updater}
  3562. Select only packages handled by @var{updater} (may be a comma-separated
  3563. list of updaters). Currently, @var{updater} may be one of:
  3564. @table @code
  3565. @item gnu
  3566. the updater for GNU packages;
  3567. @item gnome
  3568. the updater for GNOME packages;
  3569. @item elpa
  3570. the updater for @uref{http://elpa.gnu.org/, ELPA} packages;
  3571. @item cran
  3572. the updater for @uref{http://cran.r-project.org/, CRAN} packages;
  3573. @item pypi
  3574. the updater for @uref{https://pypi.python.org, PyPI} packages.
  3575. @end table
  3576. For instance, the following commands only checks for updates of Emacs
  3577. packages hosted at @code{elpa.gnu.org} and updates of CRAN packages:
  3578. @example
  3579. $ guix refresh --type=elpa,cran
  3580. gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0
  3581. gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9
  3582. @end example
  3583. @end table
  3584. In addition, @command{guix refresh} can be passed one or more package
  3585. names, as in this example:
  3586. @example
  3587. $ ./pre-inst-env guix refresh -u emacs idutils gcc-4.8.4
  3588. @end example
  3589. @noindent
  3590. The command above specifically updates the @code{emacs} and
  3591. @code{idutils} packages. The @code{--select} option would have no
  3592. effect in this case.
  3593. When considering whether to upgrade a package, it is sometimes
  3594. convenient to know which packages would be affected by the upgrade and
  3595. should be checked for compatibility. For this the following option may
  3596. be used when passing @command{guix refresh} one or more package names:
  3597. @table @code
  3598. @item --list-updaters
  3599. @itemx -L
  3600. List available updaters and exit (see @option{--type} above.)
  3601. @item --list-dependent
  3602. @itemx -l
  3603. List top-level dependent packages that would need to be rebuilt as a
  3604. result of upgrading one or more packages.
  3605. @end table
  3606. Be aware that the @code{--list-dependent} option only
  3607. @emph{approximates} the rebuilds that would be required as a result of
  3608. an upgrade. More rebuilds might be required under some circumstances.
  3609. @example
  3610. $ guix refresh --list-dependent flex
  3611. Building the following 120 packages would ensure 213 dependent packages are rebuilt:
  3612. hop-2.4.0 geiser-0.4 notmuch-0.18 mu-0.9.9.5 cflow-1.4 idutils-4.6 @dots{}
  3613. @end example
  3614. The command above lists a set of packages that could be built to check
  3615. for compatibility with an upgraded @code{flex} package.
  3616. The following options can be used to customize GnuPG operation:
  3617. @table @code
  3618. @item --gpg=@var{command}
  3619. Use @var{command} as the GnuPG 2.x command. @var{command} is searched
  3620. for in @code{$PATH}.
  3621. @item --key-download=@var{policy}
  3622. Handle missing OpenPGP keys according to @var{policy}, which may be one
  3623. of:
  3624. @table @code
  3625. @item always
  3626. Always download missing OpenPGP keys from the key server, and add them
  3627. to the user's GnuPG keyring.
  3628. @item never
  3629. Never try to download missing OpenPGP keys. Instead just bail out.
  3630. @item interactive
  3631. When a package signed with an unknown OpenPGP key is encountered, ask
  3632. the user whether to download it or not. This is the default behavior.
  3633. @end table
  3634. @item --key-server=@var{host}
  3635. Use @var{host} as the OpenPGP key server when importing a public key.
  3636. @end table
  3637. @node Invoking guix lint
  3638. @section Invoking @command{guix lint}
  3639. The @command{guix lint} is meant to help package developers avoid common
  3640. errors and use a consistent style. It runs a number of checks on a
  3641. given set of packages in order to find common mistakes in their
  3642. definitions. Available @dfn{checkers} include (see
  3643. @code{--list-checkers} for a complete list):
  3644. @table @code
  3645. @item synopsis
  3646. @itemx description
  3647. Validate certain typographical and stylistic rules about package
  3648. descriptions and synopses.
  3649. @item inputs-should-be-native
  3650. Identify inputs that should most likely be native inputs.
  3651. @item source
  3652. @itemx home-page
  3653. @itemx source-file-name
  3654. Probe @code{home-page} and @code{source} URLs and report those that are
  3655. invalid. Check that the source file name is meaningful, e.g. is not
  3656. just a version number or ``git-checkout'', and should not have a
  3657. @code{file-name} declared (@pxref{origin Reference}).
  3658. @item cve
  3659. Report known vulnerabilities found in the Common Vulnerabilities and
  3660. Exposures (CVE) database
  3661. @uref{https://nvd.nist.gov/download.cfm#CVE_FEED, published by the US
  3662. NIST}.
  3663. @item formatting
  3664. Warn about obvious source code formatting issues: trailing white space,
  3665. use of tabulations, etc.
  3666. @end table
  3667. The general syntax is:
  3668. @example
  3669. guix lint @var{options} @var{package}@dots{}
  3670. @end example
  3671. If no package is given on the command line, then all packages are checked.
  3672. The @var{options} may be zero or more of the following:
  3673. @table @code
  3674. @item --checkers
  3675. @itemx -c
  3676. Only enable the checkers specified in a comma-separated list using the
  3677. names returned by @code{--list-checkers}.
  3678. @item --list-checkers
  3679. @itemx -l
  3680. List and describe all the available checkers that will be run on packages
  3681. and exit.
  3682. @end table
  3683. @node Invoking guix size
  3684. @section Invoking @command{guix size}
  3685. The @command{guix size} command helps package developers profile the
  3686. disk usage of packages. It is easy to overlook the impact of an
  3687. additional dependency added to a package, or the impact of using a
  3688. single output for a package that could easily be split (@pxref{Packages
  3689. with Multiple Outputs}). These are the typical issues that
  3690. @command{guix size} can highlight.
  3691. The command can be passed a package specification such as @code{gcc-4.8}
  3692. or @code{guile:debug}, or a file name in the store. Consider this
  3693. example:
  3694. @example
  3695. $ guix size coreutils
  3696. store item total self
  3697. /gnu/store/@dots{}-coreutils-8.23 70.0 13.9 19.8%
  3698. /gnu/store/@dots{}-gmp-6.0.0a 55.3 2.5 3.6%
  3699. /gnu/store/@dots{}-acl-2.2.52 53.7 0.5 0.7%
  3700. /gnu/store/@dots{}-attr-2.4.46 53.2 0.3 0.5%
  3701. /gnu/store/@dots{}-gcc-4.8.4-lib 52.9 15.7 22.4%
  3702. /gnu/store/@dots{}-glibc-2.21 37.2 37.2 53.1%
  3703. @end example
  3704. @cindex closure
  3705. The store items listed here constitute the @dfn{transitive closure} of
  3706. Coreutils---i.e., Coreutils and all its dependencies, recursively---as
  3707. would be returned by:
  3708. @example
  3709. $ guix gc -R /gnu/store/@dots{}-coreutils-8.23
  3710. @end example
  3711. Here the output shows 3 columns next to store items. The first column,
  3712. labeled ``total'', shows the size in mebibytes (MiB) of the closure of
  3713. the store item---that is, its own size plus the size of all its
  3714. dependencies. The next column, labeled ``self'', shows the size of the
  3715. item itself. The last column shows the ratio of the item's size to the
  3716. space occupied by all the items listed here.
  3717. In this example, we see that the closure of Coreutils weighs in at
  3718. 70@tie{}MiB, half of which is taken by libc. (That libc represents a
  3719. large fraction of the closure is not a problem @i{per se} because it is
  3720. always available on the system anyway.)
  3721. When the package passed to @command{guix size} is available in the
  3722. store, @command{guix size} queries the daemon to determine its
  3723. dependencies, and measures its size in the store, similar to @command{du
  3724. -ms --apparent-size} (@pxref{du invocation,,, coreutils, GNU
  3725. Coreutils}).
  3726. When the given package is @emph{not} in the store, @command{guix size}
  3727. reports information based on information about the available substitutes
  3728. (@pxref{Substitutes}). This allows it to profile disk usage of store
  3729. items that are not even on disk, only available remotely.
  3730. The available options are:
  3731. @table @option
  3732. @item --substitute-urls=@var{urls}
  3733. Use substitute information from @var{urls}.
  3734. @xref{client-substitute-urls, the same option for @code{guix build}}.
  3735. @item --map-file=@var{file}
  3736. Write to @var{file} a graphical map of disk usage as a PNG file.
  3737. For the example above, the map looks like this:
  3738. @image{images/coreutils-size-map,5in,, map of Coreutils disk usage
  3739. produced by @command{guix size}}
  3740. This option requires that
  3741. @uref{http://wingolog.org/software/guile-charting/, Guile-Charting} be
  3742. installed and visible in Guile's module search path. When that is not
  3743. the case, @command{guix size} fails as it tries to load it.
  3744. @item --system=@var{system}
  3745. @itemx -s @var{system}
  3746. Consider packages for @var{system}---e.g., @code{x86_64-linux}.
  3747. @end table
  3748. @node Invoking guix graph
  3749. @section Invoking @command{guix graph}
  3750. @cindex DAG
  3751. Packages and their dependencies form a @dfn{graph}, specifically a
  3752. directed acyclic graph (DAG). It can quickly become difficult to have a
  3753. mental model of the package DAG, so the @command{guix graph} command is
  3754. here to provide a visual representation of the DAG. @command{guix
  3755. graph} emits a DAG representation in the input format of
  3756. @uref{http://www.graphviz.org/, Graphviz}, so its output can be passed
  3757. directly to Graphviz's @command{dot} command, for instance. The general
  3758. syntax is:
  3759. @example
  3760. guix graph @var{options} @var{package}@dots{}
  3761. @end example
  3762. For example, the following command generates a PDF file representing the
  3763. package DAG for the GNU@tie{}Core Utilities, showing its build-time
  3764. dependencies:
  3765. @example
  3766. guix graph coreutils | dot -Tpdf > dag.pdf
  3767. @end example
  3768. The output looks like this:
  3769. @image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils}
  3770. Nice little graph, no?
  3771. But there's more than one graph! The one above is concise: it's the
  3772. graph of package objects, omitting implicit inputs such as GCC, libc,
  3773. grep, etc. It's often useful to have such a concise graph, but
  3774. sometimes you want to see more details. @command{guix graph} supports
  3775. several types of graphs, allowing you to choose the level of details:
  3776. @table @code
  3777. @item package
  3778. This is the default type, the one we used above. It shows the DAG of
  3779. package objects, excluding implicit dependencies. It is concise, but
  3780. filters out many details.
  3781. @item bag-emerged
  3782. This is the package DAG, @emph{including} implicit inputs.
  3783. For instance, the following command:
  3784. @example
  3785. guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf
  3786. @end example
  3787. ... yields this bigger graph:
  3788. @image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU Coreutils}
  3789. At the bottom of the graph, we see all the implicit inputs of
  3790. @var{gnu-build-system} (@pxref{Build Systems, @code{gnu-build-system}}).
  3791. Now, note that the dependencies of those implicit inputs---that is, the
  3792. @dfn{bootstrap dependencies} (@pxref{Bootstrapping})---are not shown
  3793. here, for conciseness.
  3794. @item bag
  3795. Similar to @code{bag-emerged}, but this time including all the bootstrap
  3796. dependencies.
  3797. @item bag-with-origins
  3798. Similar to @code{bag}, but also showing origins and their dependencies.
  3799. @item derivations
  3800. This is the most detailed representation: It shows the DAG of
  3801. derivations (@pxref{Derivations}) and plain store items. Compared to
  3802. the above representation, many additional nodes are visible, including
  3803. builds scripts, patches, Guile modules, etc.
  3804. @end table
  3805. All the above types correspond to @emph{build-time dependencies}. The
  3806. following graph type represents the @emph{run-time dependencies}:
  3807. @table @code
  3808. @item references
  3809. This is the graph of @dfn{references} of a package output, as returned
  3810. by @command{guix gc --references} (@pxref{Invoking guix gc}).
  3811. If the given package output is not available in the store, @command{guix
  3812. graph} attempts to obtain dependency information from substitutes.
  3813. @end table
  3814. The available options are the following:
  3815. @table @option
  3816. @item --type=@var{type}
  3817. @itemx -t @var{type}
  3818. Produce a graph output of @var{type}, where @var{type} must be one of
  3819. the values listed above.
  3820. @item --list-types
  3821. List the supported graph types.
  3822. @item --expression=@var{expr}
  3823. @itemx -e @var{expr}
  3824. Consider the package @var{expr} evaluates to.
  3825. This is useful to precisely refer to a package, as in this example:
  3826. @example
  3827. guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
  3828. @end example
  3829. @end table
  3830. @node Invoking guix environment
  3831. @section Invoking @command{guix environment}
  3832. @cindex reproducible build environments
  3833. @cindex development environments
  3834. The purpose of @command{guix environment} is to assist hackers in
  3835. creating reproducible development environments without polluting their
  3836. package profile. The @command{guix environment} tool takes one or more
  3837. packages, builds all of the necessary inputs, and creates a shell
  3838. environment to use them.
  3839. The general syntax is:
  3840. @example
  3841. guix environment @var{options} @var{package}@dots{}
  3842. @end example
  3843. The following example spawns a new shell set up for the development of
  3844. GNU@tie{}Guile:
  3845. @example
  3846. guix environment guile
  3847. @end example
  3848. If the specified packages are not built yet, @command{guix environment}
  3849. automatically builds them. The new shell's environment is an augmented
  3850. version of the environment that @command{guix environment} was run in.
  3851. It contains the necessary search paths for building the given package
  3852. added to the existing environment variables. To create a ``pure''
  3853. environment in which the original environment variables have been unset,
  3854. use the @code{--pure} option@footnote{Users sometimes wrongfully augment
  3855. environment variables such as @code{PATH} in their @file{~/.bashrc}
  3856. file. As a consequence, when @code{guix environment} launches it, Bash
  3857. may read @file{~/.bashrc}, thereby introducing ``impurities'' in these
  3858. environment variables. It is an error to define such environment
  3859. variables in @file{.bashrc}; instead, they should be defined in
  3860. @file{.bash_profile}, which is sourced only by log-in shells.
  3861. @xref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}, for
  3862. details on Bash start-up files.}.
  3863. @vindex GUIX_ENVIRONMENT
  3864. @command{guix environment} defines the @code{GUIX_ENVIRONMENT}
  3865. variable in the shell it spaws. This allows users to, say, define a
  3866. specific prompt for development environments in their @file{.bashrc}
  3867. (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}):
  3868. @example
  3869. if [ -n "$GUIX_ENVIRONMENT" ]
  3870. then
  3871. export PS1="\u@@\h \w [dev]\$ "
  3872. fi
  3873. @end example
  3874. Additionally, more than one package may be specified, in which case the
  3875. union of the inputs for the given packages are used. For example, the
  3876. command below spawns a shell where all of the dependencies of both Guile
  3877. and Emacs are available:
  3878. @example
  3879. guix environment guile emacs
  3880. @end example
  3881. Sometimes an interactive shell session is not desired. An arbitrary
  3882. command may be invoked by placing the @code{--} token to separate the
  3883. command from the rest of the arguments:
  3884. @example
  3885. guix environment guile -- make -j4
  3886. @end example
  3887. In other situations, it is more convenient to specify the list of
  3888. packages needed in the environment. For example, the following command
  3889. runs @command{python} from an environment containing Python@tie{}2.7 and
  3890. NumPy:
  3891. @example
  3892. guix environment --ad-hoc python2-numpy python-2.7 -- python
  3893. @end example
  3894. Furthermore, one might want the dependencies of a package and also some
  3895. additional packages that are not build-time or runtime dependencies, but
  3896. are useful when developing nonetheless. Because of this, the
  3897. @code{--ad-hoc} flag is positional. Packages appearing before
  3898. @code{--ad-hoc} are interpreted as packages whose dependencies will be
  3899. added to the environment. Packages appearing after are interpreted as
  3900. packages that will be added to the environment directly. For example,
  3901. the following command creates a Guix development environment that
  3902. additionally includes Git and strace:
  3903. @example
  3904. guix environment guix --ad-hoc git strace
  3905. @end example
  3906. Sometimes it is desirable to isolate the environment as much as
  3907. possible, for maximal purity and reproducibility. In particular, when
  3908. using Guix on a host distro that is not GuixSD, it is desirable to
  3909. prevent access to @file{/usr/bin} and other system-wide resources from
  3910. the development environment. For example, the following command spawns
  3911. a Guile REPL in a ``container'' where only the store and the current
  3912. working directory are mounted:
  3913. @example
  3914. guix environment --ad-hoc --container guile -- guile
  3915. @end example
  3916. @quotation Note
  3917. The @code{--container} option requires Linux-libre 3.19 or newer.
  3918. @end quotation
  3919. The available options are summarized below.
  3920. @table @code
  3921. @item --expression=@var{expr}
  3922. @itemx -e @var{expr}
  3923. Create an environment for the package or list of packages that
  3924. @var{expr} evaluates to.
  3925. For example, running:
  3926. @example
  3927. guix environment -e '(@@ (gnu packages maths) petsc-openmpi)'
  3928. @end example
  3929. starts a shell with the environment for this specific variant of the
  3930. PETSc package.
  3931. Running:
  3932. @example
  3933. guix environment --ad-hoc -e '(@@ (gnu) %base-packages)'
  3934. @end example
  3935. starts a shell with all the GuixSD base packages available.
  3936. @item --load=@var{file}
  3937. @itemx -l @var{file}
  3938. Create an environment for the package or list of packages that the code
  3939. within @var{file} evaluates to.
  3940. As an example, @var{file} might contain a definition like this
  3941. (@pxref{Defining Packages}):
  3942. @example
  3943. @verbatiminclude environment-gdb.scm
  3944. @end example
  3945. @item --ad-hoc
  3946. Include all specified packages in the resulting environment, as if an
  3947. @i{ad hoc} package were defined with them as inputs. This option is
  3948. useful for quickly creating an environment without having to write a
  3949. package expression to contain the desired inputs.
  3950. For instance, the command:
  3951. @example
  3952. guix environment --ad-hoc guile guile-sdl -- guile
  3953. @end example
  3954. runs @command{guile} in an environment where Guile and Guile-SDL are
  3955. available.
  3956. Note that this example implicitly asks for the default output of
  3957. @code{guile} and @code{guile-sdl} but it is possible to ask for a
  3958. specific output---e.g., @code{glib:bin} asks for the @code{bin} output
  3959. of @code{glib} (@pxref{Packages with Multiple Outputs}).
  3960. This option may be composed with the default behavior of @command{guix
  3961. environment}. Packages appearing before @code{--ad-hoc} are interpreted
  3962. as packages whose dependencies will be added to the environment, the
  3963. default behavior. Packages appearing after are interpreted as packages
  3964. that will be added to the environment directly.
  3965. @item --pure
  3966. Unset existing environment variables when building the new environment.
  3967. This has the effect of creating an environment in which search paths
  3968. only contain package inputs.
  3969. @item --search-paths
  3970. Display the environment variable definitions that make up the
  3971. environment.
  3972. @item --system=@var{system}
  3973. @itemx -s @var{system}
  3974. Attempt to build for @var{system}---e.g., @code{i686-linux}.
  3975. @item --container
  3976. @itemx -C
  3977. @cindex container
  3978. Run @var{command} within an isolated container. The current working
  3979. directory outside the container is mapped inside the
  3980. container. Additionally, the spawned process runs as the current user
  3981. outside the container, but has root privileges in the context of the
  3982. container.
  3983. @item --network
  3984. @itemx -N
  3985. For containers, share the network namespace with the host system.
  3986. Containers created without this flag only have access to the loopback
  3987. device.
  3988. @item --expose=@var{source}[=@var{target}]
  3989. For containers, expose the file system @var{source} from the host system
  3990. as the read-only file system @var{target} within the container. If
  3991. @var{target} is not specified, @var{source} is used as the target mount
  3992. point in the container.
  3993. The example below spawns a Guile REPL in a container in which the user's
  3994. home directory is accessible read-only via the @file{/exchange}
  3995. directory:
  3996. @example
  3997. guix environment --container --expose=$HOME=/exchange guile -- guile
  3998. @end example
  3999. @item --share=@var{source}[=@var{target}]
  4000. For containers, share the file system @var{source} from the host system
  4001. as the writable file system @var{target} within the container. If
  4002. @var{target} is not specified, @var{source} is used as the target mount
  4003. point in the container.
  4004. The example below spawns a Guile REPL in a container in which the user's
  4005. home directory is accessible for both reading and writing via the
  4006. @file{/exchange} directory:
  4007. @example
  4008. guix environment --container --share=$HOME=/exchange guile -- guile
  4009. @end example
  4010. @end table
  4011. It also supports all of the common build options that @command{guix
  4012. build} supports (@pxref{Invoking guix build, common build options}).
  4013. @node Invoking guix publish
  4014. @section Invoking @command{guix publish}
  4015. The purpose of @command{guix publish} is to enable users to easily share
  4016. their store with others, which can then use it as a substitute server
  4017. (@pxref{Substitutes}).
  4018. When @command{guix publish} runs, it spawns an HTTP server which allows
  4019. anyone with network access to obtain substitutes from it. This means
  4020. that any machine running Guix can also act as if it were a build farm,
  4021. since the HTTP interface is compatible with Hydra, the software behind
  4022. the @code{hydra.gnu.org} build farm.
  4023. For security, each substitute is signed, allowing recipients to check
  4024. their authenticity and integrity (@pxref{Substitutes}). Because
  4025. @command{guix publish} uses the system's signing key, which is only
  4026. readable by the system administrator, it must be started as root; the
  4027. @code{--user} option makes it drop root privileges early on.
  4028. The signing key pair must be generated before @command{guix publish} is
  4029. launched, using @command{guix archive --generate-key} (@pxref{Invoking
  4030. guix archive}).
  4031. The general syntax is:
  4032. @example
  4033. guix publish @var{options}@dots{}
  4034. @end example
  4035. Running @command{guix publish} without any additional arguments will
  4036. spawn an HTTP server on port 8080:
  4037. @example
  4038. guix publish
  4039. @end example
  4040. Once a publishing server has been authorized (@pxref{Invoking guix
  4041. archive}), the daemon may download substitutes from it:
  4042. @example
  4043. guix-daemon --substitute-urls=http://example.org:8080
  4044. @end example
  4045. The following options are available:
  4046. @table @code
  4047. @item --port=@var{port}
  4048. @itemx -p @var{port}
  4049. Listen for HTTP requests on @var{port}.
  4050. @item --listen=@var{host}
  4051. Listen on the network interface for @var{host}. The default is to
  4052. accept connections from any interface.
  4053. @item --user=@var{user}
  4054. @itemx -u @var{user}
  4055. Change privileges to @var{user} as soon as possible---i.e., once the
  4056. server socket is open and the signing key has been read.
  4057. @item --repl[=@var{port}]
  4058. @itemx -r [@var{port}]
  4059. Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
  4060. Reference Manual}) on @var{port} (37146 by default). This is used
  4061. primarily for debugging a running @command{guix publish} server.
  4062. @end table
  4063. Enabling @command{guix publish} on a GuixSD system is a one-liner: just
  4064. add a call to @code{guix-publish-service} in the @code{services} field
  4065. of the @code{operating-system} declaration (@pxref{guix-publish-service,
  4066. @code{guix-publish-service}}).
  4067. @node Invoking guix challenge
  4068. @section Invoking @command{guix challenge}
  4069. @cindex reproducible builds
  4070. @cindex verifiable builds
  4071. Do the binaries provided by this server really correspond to the source
  4072. code it claims to build? Is this package's build process deterministic?
  4073. These are the questions the @command{guix challenge} command attempts to
  4074. answer.
  4075. The former is obviously an important question: Before using a substitute
  4076. server (@pxref{Substitutes}), you'd rather @emph{verify} that it
  4077. provides the right binaries, and thus @emph{challenge} it. The latter
  4078. is what enables the former: If package builds are deterministic, then
  4079. independent builds of the package should yield the exact same result,
  4080. bit for bit; if a server provides a binary different from the one
  4081. obtained locally, it may be either corrupt or malicious.
  4082. We know that the hash that shows up in @file{/gnu/store} file names is
  4083. the hash of all the inputs of the process that built the file or
  4084. directory---compilers, libraries, build scripts,
  4085. etc. (@pxref{Introduction}). Assuming deterministic build processes,
  4086. one store file name should map to exactly one build output.
  4087. @command{guix challenge} checks whether there is, indeed, a single
  4088. mapping by comparing the build outputs of several independent builds of
  4089. any given store item.
  4090. The command's output looks like this:
  4091. @smallexample
  4092. $ guix challenge --substitute-urls="http://hydra.gnu.org http://guix.example.org"
  4093. updating list of substitutes from 'http://hydra.gnu.org'... 100.0%
  4094. updating list of substitutes from 'http://guix.example.org'... 100.0%
  4095. /gnu/store/@dots{}-openssl-1.0.2d contents differ:
  4096. local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
  4097. http://hydra.gnu.org/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
  4098. http://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
  4099. /gnu/store/@dots{}-git-2.5.0 contents differ:
  4100. local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
  4101. http://hydra.gnu.org/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
  4102. http://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
  4103. /gnu/store/@dots{}-pius-2.1.1 contents differ:
  4104. local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
  4105. http://hydra.gnu.org/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
  4106. http://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs
  4107. @end smallexample
  4108. @noindent
  4109. In this example, @command{guix challenge} first scans the store to
  4110. determine the set of locally-built derivations---as opposed to store
  4111. items that were downloaded from a substitute server---and then queries
  4112. all the substitute servers. It then reports those store items for which
  4113. the servers obtained a result different from the local build.
  4114. @cindex non-determinism, in package builds
  4115. As an example, @code{guix.example.org} always gets a different answer.
  4116. Conversely, @code{hydra.gnu.org} agrees with local builds, except in the
  4117. case of Git. This might indicate that the build process of Git is
  4118. non-deterministic, meaning that its output varies as a function of
  4119. various things that Guix does not fully control, in spite of building
  4120. packages in isolated environments (@pxref{Features}). Most common
  4121. sources of non-determinism include the addition of timestamps in build
  4122. results, the inclusion of random numbers, and directory listings sorted
  4123. by inode number. See @uref{http://reproducible.debian.net/howto/}, for
  4124. more information.
  4125. To find out what's wrong with this Git binary, we can do something along
  4126. these lines (@pxref{Invoking guix archive}):
  4127. @example
  4128. $ wget -q -O - http://hydra.gnu.org/nar/@dots{}-git-2.5.0 \
  4129. | guix archive -x /tmp/git
  4130. $ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
  4131. @end example
  4132. This command shows the difference between the files resulting from the
  4133. local build, and the files resulting from the build on
  4134. @code{hydra.gnu.org} (@pxref{Overview, Comparing and Merging Files,,
  4135. diffutils, Comparing and Merging Files}). The @command{diff} command
  4136. works great for text files. When binary files differ, a better option
  4137. is @uref{http://diffoscope.org/, Diffoscope}, a tool that helps
  4138. visualize differences for all kinds of files.
  4139. Once you've done that work, you can tell whether the differences are due
  4140. to a non-deterministic build process or to a malicious server. We try
  4141. hard to remove sources of non-determinism in packages to make it easier
  4142. to verify substitutes, but of course, this is a process, one that
  4143. involves not just Guix but a large part of the free software community.
  4144. In the meantime, @command{guix challenge} is one tool to help address
  4145. the problem.
  4146. If you are writing packages for Guix, you are encouraged to check
  4147. whether @code{hydra.gnu.org} and other substitute servers obtain the
  4148. same build result as you did with:
  4149. @example
  4150. $ guix challenge @var{package}
  4151. @end example
  4152. @noindent
  4153. ... where @var{package} is a package specification such as
  4154. @code{guile-2.0} or @code{glibc:debug}.
  4155. The general syntax is:
  4156. @example
  4157. guix challenge @var{options} [@var{packages}@dots{}]
  4158. @end example
  4159. The one option that matters is:
  4160. @table @code
  4161. @item --substitute-urls=@var{urls}
  4162. Consider @var{urls} the whitespace-separated list of substitute source
  4163. URLs to compare to.
  4164. @end table
  4165. @node Invoking guix container
  4166. @section Invoking @command{guix container}
  4167. @cindex container
  4168. @quotation Note
  4169. As of version @value{VERSION}, this tool is experimental. The interface
  4170. is subject to radical change in the future.
  4171. @end quotation
  4172. The purpose of @command{guix container} is to manipulate processes
  4173. running within an isolated environment, commonly known as a
  4174. ``container'', typically created by the @command{guix environment}
  4175. (@pxref{Invoking guix environment}) and @command{guix system container}
  4176. (@pxref{Invoking guix system}) commands.
  4177. The general syntax is:
  4178. @example
  4179. guix container @var{action} @var{options}@dots{}
  4180. @end example
  4181. @var{action} specifies the operation to perform with a container, and
  4182. @var{options} specifies the context-specific arguments for the action.
  4183. The following actions are available:
  4184. @table @code
  4185. @item exec
  4186. Execute a command within the context of a running container.
  4187. The syntax is:
  4188. @example
  4189. guix container exec @var{pid} @var{program} @var{arguments}@dots{}
  4190. @end example
  4191. @var{pid} specifies the process ID of the running container.
  4192. @var{program} specifies an executable file name within the container's
  4193. root file system. @var{arguments} are the additional options that will
  4194. be passed to @var{program}.
  4195. The following command launches an interactive login shell inside a
  4196. GuixSD container, started by @command{guix system container}, and whose
  4197. process ID is 9001:
  4198. @example
  4199. guix container exec 9001 /run/current-system/profile/bin/bash --login
  4200. @end example
  4201. Note that the @var{pid} cannot be the parent process of a container. It
  4202. must be the container's PID 1 or one of its child processes.
  4203. @end table
  4204. @c *********************************************************************
  4205. @node GNU Distribution
  4206. @chapter GNU Distribution
  4207. @cindex Guix System Distribution
  4208. @cindex GuixSD
  4209. Guix comes with a distribution of the GNU system consisting entirely of
  4210. free software@footnote{The term ``free'' here refers to the
  4211. @url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
  4212. users of that software}.}. The
  4213. distribution can be installed on its own (@pxref{System Installation}),
  4214. but it is also possible to install Guix as a package manager on top of
  4215. an installed GNU/Linux system (@pxref{Installation}). To distinguish
  4216. between the two, we refer to the standalone distribution as the Guix
  4217. System Distribution, or GuixSD.
  4218. The distribution provides core GNU packages such as GNU libc, GCC, and
  4219. Binutils, as well as many GNU and non-GNU applications. The complete
  4220. list of available packages can be browsed
  4221. @url{http://www.gnu.org/software/guix/packages,on-line} or by
  4222. running @command{guix package} (@pxref{Invoking guix package}):
  4223. @example
  4224. guix package --list-available
  4225. @end example
  4226. Our goal has been to provide a practical 100% free software distribution of
  4227. Linux-based and other variants of GNU, with a focus on the promotion and
  4228. tight integration of GNU components, and an emphasis on programs and
  4229. tools that help users exert that freedom.
  4230. Packages are currently available on the following platforms:
  4231. @table @code
  4232. @item x86_64-linux
  4233. Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
  4234. @item i686-linux
  4235. Intel 32-bit architecture (IA32), Linux-Libre kernel;
  4236. @item armhf-linux
  4237. ARMv7-A architecture with hard float, Thumb-2 and NEON,
  4238. using the EABI hard-float ABI, and Linux-Libre kernel.
  4239. @item mips64el-linux
  4240. little-endian 64-bit MIPS processors, specifically the Loongson series,
  4241. n32 application binary interface (ABI), and Linux-Libre kernel.
  4242. @end table
  4243. GuixSD itself is currently only available on @code{i686} and @code{x86_64}.
  4244. @noindent
  4245. For information on porting to other architectures or kernels,
  4246. @xref{Porting}.
  4247. @menu
  4248. * System Installation:: Installing the whole operating system.
  4249. * System Configuration:: Configuring the operating system.
  4250. * Installing Debugging Files:: Feeding the debugger.
  4251. * Security Updates:: Deploying security fixes quickly.
  4252. * Package Modules:: Packages from the programmer's viewpoint.
  4253. * Packaging Guidelines:: Growing the distribution.
  4254. * Bootstrapping:: GNU/Linux built from scratch.
  4255. * Porting:: Targeting another platform or kernel.
  4256. @end menu
  4257. Building this distribution is a cooperative effort, and you are invited
  4258. to join! @xref{Contributing}, for information about how you can help.
  4259. @node System Installation
  4260. @section System Installation
  4261. @cindex Guix System Distribution
  4262. This section explains how to install the Guix System Distribution
  4263. on a machine. The Guix package manager can
  4264. also be installed on top of a running GNU/Linux system,
  4265. @pxref{Installation}.
  4266. @ifinfo
  4267. @c This paragraph is for people reading this from tty2 of the
  4268. @c installation image.
  4269. You're reading this documentation with an Info reader. For details on
  4270. how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
  4271. link that follows: @pxref{Help,,, info, Info: An Introduction}. Hit
  4272. @kbd{l} afterwards to come back here.
  4273. @end ifinfo
  4274. @subsection Limitations
  4275. As of version @value{VERSION}, the Guix System Distribution (GuixSD) is
  4276. not production-ready. It may contain bugs and lack important
  4277. features. Thus, if you are looking for a stable production system that
  4278. respects your freedom as a computer user, a good solution at this point
  4279. is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
  4280. more established GNU/Linux distributions}. We hope you can soon switch
  4281. to the GuixSD without fear, of course. In the meantime, you can
  4282. also keep using your distribution and try out the package manager on top
  4283. of it (@pxref{Installation}).
  4284. Before you proceed with the installation, be aware of the following
  4285. noteworthy limitations applicable to version @value{VERSION}:
  4286. @itemize
  4287. @item
  4288. The installation process does not include a graphical user interface and
  4289. requires familiarity with GNU/Linux (see the following subsections to
  4290. get a feel of what that means.)
  4291. @item
  4292. The system does not yet provide full GNOME and KDE desktops. Xfce and
  4293. Enlightenment are available though, if graphical desktop environments
  4294. are your thing, as well as a number of X11 window managers.
  4295. @item
  4296. Support for the Logical Volume Manager (LVM) is missing.
  4297. @item
  4298. Few system services are currently supported out-of-the-box
  4299. (@pxref{Services}).
  4300. @item
  4301. More than 2,000 packages are available, but you may
  4302. occasionally find that a useful package is missing.
  4303. @end itemize
  4304. You've been warned. But more than a disclaimer, this is an invitation
  4305. to report issues (and success stories!), and join us in improving it.
  4306. @xref{Contributing}, for more info.
  4307. @subsection USB Stick Installation
  4308. An installation image for USB sticks can be downloaded from
  4309. @indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-usb-install-@value{VERSION}.@var{system}.xz},
  4310. where @var{system} is one of:
  4311. @table @code
  4312. @item x86_64-linux
  4313. for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
  4314. @item i686-linux
  4315. for a 32-bit GNU/Linux system on Intel-compatible CPUs.
  4316. @end table
  4317. This image contains a single partition with the tools necessary for an
  4318. installation. It is meant to be copied @emph{as is} to a large-enough
  4319. USB stick.
  4320. To copy the image to a USB stick, follow these steps:
  4321. @enumerate
  4322. @item
  4323. Decompress the image using the @command{xz} command:
  4324. @example
  4325. xz -d guixsd-usb-install-@value{VERSION}.@var{system}.xz
  4326. @end example
  4327. @item
  4328. Insert a USB stick of 1@tie{}GiB or more in your machine, and determine
  4329. its device name. Assuming that USB stick is known as @file{/dev/sdX},
  4330. copy the image with:
  4331. @example
  4332. dd if=guixsd-usb-install-@value{VERSION}.x86_64 of=/dev/sdX
  4333. @end example
  4334. Access to @file{/dev/sdX} usually requires root privileges.
  4335. @end enumerate
  4336. Once this is done, you should be able to reboot the system and boot from
  4337. the USB stick. The latter usually requires you to get in the BIOS' boot
  4338. menu, where you can choose to boot from the USB stick.
  4339. @subsection Preparing for Installation
  4340. Once you have successfully booted the image on the USB stick, you should
  4341. end up with a root prompt. Several console TTYs are configured and can
  4342. be used to run commands as root. TTY2 shows this documentation,
  4343. browsable using the Info reader commands (@pxref{Help,,, info, Info: An
  4344. Introduction}). The installation system runs the GPM mouse daemon,
  4345. which allows you to select text with the left mouse button and to paste
  4346. it with the middle button.
  4347. To install the system, you would:
  4348. @enumerate
  4349. @item
  4350. Configure the network, by running:
  4351. @example
  4352. ifconfig eno1 up && dhclient eno1
  4353. @end example
  4354. to get an automatically assigned IP address from the wired
  4355. network interface controller@footnote{
  4356. @c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
  4357. The name @code{eno1} is for the first on-board Ethernet controller. The
  4358. interface name for an Ethernet controller that is in the first slot of
  4359. the first PCI bus, for instance, would be @code{enp1s0}. Use
  4360. @command{ifconfig -a} to list all the available network interfaces.},
  4361. or using the @command{ifconfig} command.
  4362. The system automatically loads drivers for your network interface
  4363. controllers.
  4364. Setting up network access is almost always a requirement because the
  4365. image does not contain all the software and tools that may be needed.
  4366. @item
  4367. Unless this has already been done, you must partition, and then format
  4368. the target partition.
  4369. Preferably, assign partitions a label so that you can easily and
  4370. reliably refer to them in @code{file-system} declarations (@pxref{File
  4371. Systems}). This is typically done using the @code{-L} option of
  4372. @command{mkfs.ext4} and related commands.
  4373. Be sure that your partition labels match the value of their respective
  4374. @code{device} fields in your @code{file-system} configuration, if your
  4375. @code{file-system} configuration sets the value of @code{title} to
  4376. @code{'label}, as do the example configurations found on the USB
  4377. installation image under @file{/etc/configuration} (@pxref{Using the
  4378. Configuration System}).
  4379. @c FIXME: Uncomment this once GRUB fully supports encrypted roots.
  4380. @c A typical command sequence may be:
  4381. @c
  4382. @c @example
  4383. @c # fdisk /dev/sdX
  4384. @c @dots{} Create partitions etc.@dots{}
  4385. @c # cryptsetup luksFormat /dev/sdX1
  4386. @c # cryptsetup open --type luks /dev/sdX1 my-partition
  4387. @c # mkfs.ext4 -L my-root /dev/mapper/my-partition
  4388. @c @end example
  4389. The installation image includes Parted (@pxref{Overview,,, parted, GNU
  4390. Parted User Manual}), @command{fdisk}, Cryptsetup/LUKS for disk
  4391. encryption, and e2fsprogs, the suite of tools to manipulate
  4392. ext2/ext3/ext4 file systems.
  4393. @item
  4394. Once that is done, mount the target root partition under @file{/mnt}.
  4395. @item
  4396. Lastly, run @code{deco start cow-store /mnt}.
  4397. This will make @file{/gnu/store} copy-on-write, such that packages added
  4398. to it during the installation phase will be written to the target disk
  4399. rather than kept in memory.
  4400. @end enumerate
  4401. @subsection Proceeding with the Installation
  4402. With the target partitions ready, you now have to edit a file and
  4403. provide the declaration of the operating system to be installed. To
  4404. that end, the installation system comes with two text editors: GNU nano
  4405. (@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone.
  4406. It is better to store that file on the target root file system, say, as
  4407. @file{/mnt/etc/config.scm}.
  4408. @xref{Using the Configuration System}, for examples of operating system
  4409. configurations. These examples are available under
  4410. @file{/etc/configuration} in the installation image, so you can copy
  4411. them and use them as a starting point for your own configuration.
  4412. Once you are done preparing the configuration file, the new system must
  4413. be initialized (remember that the target root file system is mounted
  4414. under @file{/mnt}):
  4415. @example
  4416. guix system init /mnt/etc/config.scm /mnt
  4417. @end example
  4418. @noindent
  4419. This will copy all the necessary files, and install GRUB on
  4420. @file{/dev/sdX}, unless you pass the @option{--no-grub} option. For
  4421. more information, @pxref{Invoking guix system}. This command may trigger
  4422. downloads or builds of missing packages, which can take some time.
  4423. Once that command has completed---and hopefully succeeded!---you can run
  4424. @command{reboot} and boot into the new system. The @code{root} password
  4425. in the new system is initially empty; other users' passwords need to be
  4426. initialized by running the @command{passwd} command as @code{root},
  4427. unless your configuration specifies otherwise
  4428. (@pxref{user-account-password, user account passwords}).
  4429. Join us on @code{#guix} on the Freenode IRC network or on
  4430. @file{guix-devel@@gnu.org} to share your experience---good or not so
  4431. good.
  4432. @subsection Building the Installation Image
  4433. The installation image described above was built using the @command{guix
  4434. system} command, specifically:
  4435. @example
  4436. guix system disk-image --image-size=850MiB gnu/system/install.scm
  4437. @end example
  4438. @xref{Invoking guix system}, for more information. See
  4439. @file{gnu/system/install.scm} in the source tree for more information
  4440. about the installation image.
  4441. @node System Configuration
  4442. @section System Configuration
  4443. @cindex system configuration
  4444. The Guix System Distribution supports a consistent whole-system configuration
  4445. mechanism. By that we mean that all aspects of the global system
  4446. configuration---such as the available system services, timezone and
  4447. locale settings, user accounts---are declared in a single place. Such
  4448. a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
  4449. One of the advantages of putting all the system configuration under the
  4450. control of Guix is that it supports transactional system upgrades, and
  4451. makes it possible to roll-back to a previous system instantiation,
  4452. should something go wrong with the new one (@pxref{Features}). Another
  4453. one is that it makes it easy to replicate the exact same configuration
  4454. across different machines, or at different points in time, without
  4455. having to resort to additional administration tools layered on top of
  4456. the system's own tools.
  4457. @c Yes, we're talking of Puppet, Chef, & co. here. ↑
  4458. This section describes this mechanism. First we focus on the system
  4459. administrator's viewpoint---explaining how the system is configured and
  4460. instantiated. Then we show how this mechanism can be extended, for
  4461. instance to support new system services.
  4462. @menu
  4463. * Using the Configuration System:: Customizing your GNU system.
  4464. * operating-system Reference:: Detail of operating-system declarations.
  4465. * File Systems:: Configuring file system mounts.
  4466. * Mapped Devices:: Block device extra processing.
  4467. * User Accounts:: Specifying user accounts.
  4468. * Locales:: Language and cultural convention settings.
  4469. * Services:: Specifying system services.
  4470. * Setuid Programs:: Programs running with root privileges.
  4471. * X.509 Certificates:: Authenticating HTTPS servers.
  4472. * Name Service Switch:: Configuring libc's name service switch.
  4473. * Initial RAM Disk:: Linux-Libre bootstrapping.
  4474. * GRUB Configuration:: Configuring the boot loader.
  4475. * Invoking guix system:: Instantiating a system configuration.
  4476. * Defining Services:: Adding new service definitions.
  4477. @end menu
  4478. @node Using the Configuration System
  4479. @subsection Using the Configuration System
  4480. The operating system is configured by providing an
  4481. @code{operating-system} declaration in a file that can then be passed to
  4482. the @command{guix system} command (@pxref{Invoking guix system}). A
  4483. simple setup, with the default system services, the default Linux-Libre
  4484. kernel, initial RAM disk, and boot loader looks like this:
  4485. @findex operating-system
  4486. @lisp
  4487. @include os-config-bare-bones.texi
  4488. @end lisp
  4489. This example should be self-describing. Some of the fields defined
  4490. above, such as @code{host-name} and @code{bootloader}, are mandatory.
  4491. Others, such as @code{packages} and @code{services}, can be omitted, in
  4492. which case they get a default value.
  4493. @vindex %base-packages
  4494. The @code{packages} field lists
  4495. packages that will be globally visible on the system, for all user
  4496. accounts---i.e., in every user's @code{PATH} environment variable---in
  4497. addition to the per-user profiles (@pxref{Invoking guix package}). The
  4498. @var{%base-packages} variable provides all the tools one would expect
  4499. for basic user and administrator tasks---including the GNU Core
  4500. Utilities, the GNU Networking Utilities, the GNU Zile lightweight text
  4501. editor, @command{find}, @command{grep}, etc. The example above adds
  4502. tcpdump to those, taken from the @code{(gnu packages admin)} module
  4503. (@pxref{Package Modules}).
  4504. @findex specification->package
  4505. Referring to packages by variable name, like @var{tcpdump} above, has
  4506. the advantage of being unambiguous; it also allows typos and such to be
  4507. diagnosed right away as ``unbound variables''. The downside is that one
  4508. needs to know which module defines which package, and to augment the
  4509. @code{use-package-modules} line accordingly. To avoid that, one can use
  4510. the @code{specification->package} procedure of the @code{(gnu packages)}
  4511. module, which returns the best package for a given name or name and
  4512. version:
  4513. @lisp
  4514. (use-modules (gnu packages))
  4515. (operating-system
  4516. ;; ...
  4517. (packages (append (map specification->package
  4518. '("tcpdump" "htop" "gnupg-2.0"))
  4519. %base-packages)))
  4520. @end lisp
  4521. @vindex %base-services
  4522. The @code{services} field lists @dfn{system services} to be made
  4523. available when the system starts (@pxref{Services}).
  4524. The @code{operating-system} declaration above specifies that, in
  4525. addition to the basic services, we want the @command{lshd} secure shell
  4526. daemon listening on port 2222 (@pxref{Networking Services,
  4527. @code{lsh-service}}). Under the hood,
  4528. @code{lsh-service} arranges so that @code{lshd} is started with the
  4529. right command-line options, possibly with supporting configuration files
  4530. generated as needed (@pxref{Defining Services}).
  4531. @cindex customization, of services
  4532. @findex modify-services
  4533. Occasionally, instead of using the base services as is, you will want to
  4534. customize them. For instance, to change the configuration of
  4535. @code{guix-daemon} and Mingetty (the console log-in), you may write the
  4536. following instead of @var{%base-services}:
  4537. @lisp
  4538. (modify-services %base-services
  4539. (guix-service-type config =>
  4540. (guix-configuration
  4541. (inherit config)
  4542. (use-substitutes? #f)
  4543. (extra-options '("--gc-keep-outputs"))))
  4544. (mingetty-service-type config =>
  4545. (mingetty-configuration
  4546. (inherit config)
  4547. (motd (plain-file "motd" "Hi there!")))))
  4548. @end lisp
  4549. @noindent
  4550. The effect here is to change the options passed to @command{guix-daemon}
  4551. when it is started, as well as the ``message of the day'' that appears
  4552. when logging in at the console. @xref{Service Reference,
  4553. @code{modify-services}}, for more on that.
  4554. The configuration for a typical ``desktop'' usage, with the X11 display
  4555. server, a desktop environment, network management, power management, and
  4556. more, would look like this:
  4557. @lisp
  4558. @include os-config-desktop.texi
  4559. @end lisp
  4560. @xref{Desktop Services}, for the exact list of services provided by
  4561. @var{%desktop-services}. @xref{X.509 Certificates}, for background
  4562. information about the @code{nss-certs} package that is used here.
  4563. @xref{operating-system Reference}, for details about all the available
  4564. @code{operating-system} fields.
  4565. Assuming the above snippet is stored in the @file{my-system-config.scm}
  4566. file, the @command{guix system reconfigure my-system-config.scm} command
  4567. instantiates that configuration, and makes it the default GRUB boot
  4568. entry (@pxref{Invoking guix system}).
  4569. The normal way to change the system's configuration is by updating this
  4570. file and re-running @command{guix system reconfigure}. One should never
  4571. have to touch files in @command{/etc} or to run commands that modify the
  4572. system state such as @command{useradd} or @command{grub-install}. In
  4573. fact, you must avoid that since that would not only void your warranty
  4574. but also prevent you from rolling back to previous versions of your
  4575. system, should you ever need to.
  4576. @cindex roll-back, of the operating system
  4577. Speaking of roll-back, each time you run @command{guix system
  4578. reconfigure}, a new @dfn{generation} of the system is created---without
  4579. modifying or deleting previous generations. Old system generations get
  4580. an entry in the GRUB boot menu, allowing you to boot them in case
  4581. something went wrong with the latest generation. Reassuring, no? The
  4582. @command{guix system list-generations} command lists the system
  4583. generations available on disk.
  4584. At the Scheme level, the bulk of an @code{operating-system} declaration
  4585. is instantiated with the following monadic procedure (@pxref{The Store
  4586. Monad}):
  4587. @deffn {Monadic Procedure} operating-system-derivation os
  4588. Return a derivation that builds @var{os}, an @code{operating-system}
  4589. object (@pxref{Derivations}).
  4590. The output of the derivation is a single directory that refers to all
  4591. the packages, configuration files, and other supporting files needed to
  4592. instantiate @var{os}.
  4593. @end deffn
  4594. @node operating-system Reference
  4595. @subsection @code{operating-system} Reference
  4596. This section summarizes all the options available in
  4597. @code{operating-system} declarations (@pxref{Using the Configuration
  4598. System}).
  4599. @deftp {Data Type} operating-system
  4600. This is the data type representing an operating system configuration.
  4601. By that, we mean all the global system configuration, not per-user
  4602. configuration (@pxref{Using the Configuration System}).
  4603. @table @asis
  4604. @item @code{kernel} (default: @var{linux-libre})
  4605. The package object of the operating system kernel to use@footnote{Currently
  4606. only the Linux-libre kernel is supported. In the future, it will be
  4607. possible to use the GNU@tie{}Hurd.}.
  4608. @item @code{kernel-arguments} (default: @code{'()})
  4609. List of strings or gexps representing additional arguments to pass on
  4610. the kernel's command-line---e.g., @code{("console=ttyS0")}.
  4611. @item @code{bootloader}
  4612. The system bootloader configuration object. @xref{GRUB Configuration}.
  4613. @item @code{initrd} (default: @code{base-initrd})
  4614. A two-argument monadic procedure that returns an initial RAM disk for
  4615. the Linux kernel. @xref{Initial RAM Disk}.
  4616. @item @code{firmware} (default: @var{%base-firmware})
  4617. @cindex firmware
  4618. List of firmware packages loadable by the operating system kernel.
  4619. The default includes firmware needed for Atheros-based WiFi devices
  4620. (Linux-libre module @code{ath9k}.)
  4621. @item @code{host-name}
  4622. The host name.
  4623. @item @code{hosts-file}
  4624. @cindex hosts file
  4625. A file-like object (@pxref{G-Expressions, file-like objects}) for use as
  4626. @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
  4627. Reference Manual}). The default is a file with entries for
  4628. @code{localhost} and @var{host-name}.
  4629. @item @code{mapped-devices} (default: @code{'()})
  4630. A list of mapped devices. @xref{Mapped Devices}.
  4631. @item @code{file-systems}
  4632. A list of file systems. @xref{File Systems}.
  4633. @item @code{swap-devices} (default: @code{'()})
  4634. @cindex swap devices
  4635. A list of strings identifying devices to be used for ``swap space''
  4636. (@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}).
  4637. For example, @code{'("/dev/sda3")}.
  4638. @item @code{users} (default: @code{%base-user-accounts})
  4639. @itemx @code{groups} (default: @var{%base-groups})
  4640. List of user accounts and groups. @xref{User Accounts}.
  4641. @item @code{skeletons} (default: @code{(default-skeletons)})
  4642. A monadic list of pairs of target file name and files. These are the
  4643. files that will be used as skeletons as new accounts are created.
  4644. For instance, a valid value may look like this:
  4645. @example
  4646. (mlet %store-monad ((bashrc (text-file "bashrc" "\
  4647. export PATH=$HOME/.guix-profile/bin")))
  4648. (return `((".bashrc" ,bashrc))))
  4649. @end example
  4650. @item @code{issue} (default: @var{%default-issue})
  4651. A string denoting the contents of the @file{/etc/issue} file, which is
  4652. what displayed when users log in on a text console.
  4653. @item @code{packages} (default: @var{%base-packages})
  4654. The set of packages installed in the global profile, which is accessible
  4655. at @file{/run/current-system/profile}.
  4656. The default set includes core utilities, but it is good practice to
  4657. install non-core utilities in user profiles (@pxref{Invoking guix
  4658. package}).
  4659. @item @code{timezone}
  4660. A timezone identifying string---e.g., @code{"Europe/Paris"}.
  4661. @item @code{locale} (default: @code{"en_US.utf8"})
  4662. The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
  4663. Library Reference Manual}). @xref{Locales}, for more information.
  4664. @item @code{locale-definitions} (default: @var{%default-locale-definitions})
  4665. The list of locale definitions to be compiled and that may be used at
  4666. run time. @xref{Locales}.
  4667. @item @code{locale-libcs} (default: @code{(list @var{glibc})})
  4668. The list of GNU@tie{}libc packages whose locale data and tools are used
  4669. to build the locale definitions. @xref{Locales}, for compatibility
  4670. considerations that justify this option.
  4671. @item @code{name-service-switch} (default: @var{%default-nss})
  4672. Configuration of libc's name service switch (NSS)---a
  4673. @code{<name-service-switch>} object. @xref{Name Service Switch}, for
  4674. details.
  4675. @item @code{services} (default: @var{%base-services})
  4676. A list of service objects denoting system services. @xref{Services}.
  4677. @item @code{pam-services} (default: @code{(base-pam-services)})
  4678. @cindex PAM
  4679. @cindex pluggable authentication modules
  4680. Linux @dfn{pluggable authentication module} (PAM) services.
  4681. @c FIXME: Add xref to PAM services section.
  4682. @item @code{setuid-programs} (default: @var{%setuid-programs})
  4683. List of string-valued G-expressions denoting setuid programs.
  4684. @xref{Setuid Programs}.
  4685. @item @code{sudoers-file} (default: @var{%sudoers-specification})
  4686. @cindex sudoers file
  4687. The contents of the @file{/etc/sudoers} file as a file-like object
  4688. (@pxref{G-Expressions, @code{local-file} and @code{plain-file}}).
  4689. This file specifies which users can use the @command{sudo} command, what
  4690. they are allowed to do, and what privileges they may gain. The default
  4691. is that only @code{root} and members of the @code{wheel} group may use
  4692. @code{sudo}.
  4693. @end table
  4694. @end deftp
  4695. @node File Systems
  4696. @subsection File Systems
  4697. The list of file systems to be mounted is specified in the
  4698. @code{file-systems} field of the operating system's declaration
  4699. (@pxref{Using the Configuration System}). Each file system is declared
  4700. using the @code{file-system} form, like this:
  4701. @example
  4702. (file-system
  4703. (mount-point "/home")
  4704. (device "/dev/sda3")
  4705. (type "ext4"))
  4706. @end example
  4707. As usual, some of the fields are mandatory---those shown in the example
  4708. above---while others can be omitted. These are described below.
  4709. @deftp {Data Type} file-system
  4710. Objects of this type represent file systems to be mounted. They
  4711. contain the following members:
  4712. @table @asis
  4713. @item @code{type}
  4714. This is a string specifying the type of the file system---e.g.,
  4715. @code{"ext4"}.
  4716. @item @code{mount-point}
  4717. This designates the place where the file system is to be mounted.
  4718. @item @code{device}
  4719. This names the ``source'' of the file system. By default it is the name
  4720. of a node under @file{/dev}, but its meaning depends on the @code{title}
  4721. field described below.
  4722. @item @code{title} (default: @code{'device})
  4723. This is a symbol that specifies how the @code{device} field is to be
  4724. interpreted.
  4725. When it is the symbol @code{device}, then the @code{device} field is
  4726. interpreted as a file name; when it is @code{label}, then @code{device}
  4727. is interpreted as a partition label name; when it is @code{uuid},
  4728. @code{device} is interpreted as a partition unique identifier (UUID).
  4729. UUIDs may be converted from their string representation (as shown by the
  4730. @command{tune2fs -l} command) using the @code{uuid} form, like this:
  4731. @example
  4732. (file-system
  4733. (mount-point "/home")
  4734. (type "ext4")
  4735. (title 'uuid)
  4736. (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
  4737. @end example
  4738. The @code{label} and @code{uuid} options offer a way to refer to disk
  4739. partitions without having to hard-code their actual device
  4740. name@footnote{Note that, while it is tempting to use
  4741. @file{/dev/disk/by-uuid} and similar device names to achieve the same
  4742. result, this is not recommended: These special device nodes are created
  4743. by the udev daemon and may be unavailable at the time the device is
  4744. mounted.}.
  4745. However, when a file system's source is a mapped device (@pxref{Mapped
  4746. Devices}), its @code{device} field @emph{must} refer to the mapped
  4747. device name---e.g., @file{/dev/mapper/root-partition}---and consequently
  4748. @code{title} must be set to @code{'device}. This is required so that
  4749. the system knows that mounting the file system depends on having the
  4750. corresponding device mapping established.
  4751. @item @code{flags} (default: @code{'()})
  4752. This is a list of symbols denoting mount flags. Recognized flags
  4753. include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
  4754. access to special files), @code{no-suid} (ignore setuid and setgid
  4755. bits), and @code{no-exec} (disallow program execution.)
  4756. @item @code{options} (default: @code{#f})
  4757. This is either @code{#f}, or a string denoting mount options.
  4758. @item @code{mount?} (default: @code{#t})
  4759. This value indicates whether to automatically mount the file system when
  4760. the system is brought up. When set to @code{#f}, the file system gets
  4761. an entry in @file{/etc/fstab} (read by the @command{mount} command) but
  4762. is not automatically mounted.
  4763. @item @code{needed-for-boot?} (default: @code{#f})
  4764. This Boolean value indicates whether the file system is needed when
  4765. booting. If that is true, then the file system is mounted when the
  4766. initial RAM disk (initrd) is loaded. This is always the case, for
  4767. instance, for the root file system.
  4768. @item @code{check?} (default: @code{#t})
  4769. This Boolean indicates whether the file system needs to be checked for
  4770. errors before being mounted.
  4771. @item @code{create-mount-point?} (default: @code{#f})
  4772. When true, the mount point is created if it does not exist yet.
  4773. @item @code{dependencies} (default: @code{'()})
  4774. This is a list of @code{<file-system>} objects representing file systems
  4775. that must be mounted before (and unmounted after) this one.
  4776. As an example, consider a hierarchy of mounts: @file{/sys/fs/cgroup} is
  4777. a dependency of @file{/sys/fs/cgroup/cpu} and
  4778. @file{/sys/fs/cgroup/memory}.
  4779. @end table
  4780. @end deftp
  4781. The @code{(gnu system file-systems)} exports the following useful
  4782. variables.
  4783. @defvr {Scheme Variable} %base-file-systems
  4784. These are essential file systems that are required on normal systems,
  4785. such as @var{%pseudo-terminal-file-system} and @var{%immutable-store} (see
  4786. below.) Operating system declarations should always contain at least
  4787. these.
  4788. @end defvr
  4789. @defvr {Scheme Variable} %pseudo-terminal-file-system
  4790. This is the file system to be mounted as @file{/dev/pts}. It supports
  4791. @dfn{pseudo-terminals} created @i{via} @code{openpty} and similar
  4792. functions (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference
  4793. Manual}). Pseudo-terminals are used by terminal emulators such as
  4794. @command{xterm}.
  4795. @end defvr
  4796. @defvr {Scheme Variable} %shared-memory-file-system
  4797. This file system is mounted as @file{/dev/shm} and is used to support
  4798. memory sharing across processes (@pxref{Memory-mapped I/O,
  4799. @code{shm_open},, libc, The GNU C Library Reference Manual}).
  4800. @end defvr
  4801. @defvr {Scheme Variable} %immutable-store
  4802. This file system performs a read-only ``bind mount'' of
  4803. @file{/gnu/store}, making it read-only for all the users including
  4804. @code{root}. This prevents against accidental modification by software
  4805. running as @code{root} or by system administrators.
  4806. The daemon itself is still able to write to the store: it remounts it
  4807. read-write in its own ``name space.''
  4808. @end defvr
  4809. @defvr {Scheme Variable} %binary-format-file-system
  4810. The @code{binfmt_misc} file system, which allows handling of arbitrary
  4811. executable file types to be delegated to user space. This requires the
  4812. @code{binfmt.ko} kernel module to be loaded.
  4813. @end defvr
  4814. @defvr {Scheme Variable} %fuse-control-file-system
  4815. The @code{fusectl} file system, which allows unprivileged users to mount
  4816. and unmount user-space FUSE file systems. This requires the
  4817. @code{fuse.ko} kernel module to be loaded.
  4818. @end defvr
  4819. @node Mapped Devices
  4820. @subsection Mapped Devices
  4821. @cindex device mapping
  4822. @cindex mapped devices
  4823. The Linux kernel has a notion of @dfn{device mapping}: a block device,
  4824. such as a hard disk partition, can be @dfn{mapped} into another device,
  4825. with additional processing over the data that flows through
  4826. it@footnote{Note that the GNU@tie{}Hurd makes no difference between the
  4827. concept of a ``mapped device'' and that of a file system: both boil down
  4828. to @emph{translating} input/output operations made on a file to
  4829. operations on its backing store. Thus, the Hurd implements mapped
  4830. devices, like file systems, using the generic @dfn{translator} mechanism
  4831. (@pxref{Translators,,, hurd, The GNU Hurd Reference Manual}).}. A
  4832. typical example is encryption device mapping: all writes to the mapped
  4833. device are encrypted, and all reads are deciphered, transparently.
  4834. Mapped devices are declared using the @code{mapped-device} form:
  4835. @example
  4836. (mapped-device
  4837. (source "/dev/sda3")
  4838. (target "home")
  4839. (type luks-device-mapping))
  4840. @end example
  4841. @noindent
  4842. @cindex disk encryption
  4843. @cindex LUKS
  4844. This example specifies a mapping from @file{/dev/sda3} to
  4845. @file{/dev/mapper/home} using LUKS---the
  4846. @url{http://code.google.com/p/cryptsetup,Linux Unified Key Setup}, a
  4847. standard mechanism for disk encryption. The @file{/dev/mapper/home}
  4848. device can then be used as the @code{device} of a @code{file-system}
  4849. declaration (@pxref{File Systems}). The @code{mapped-device} form is
  4850. detailed below.
  4851. @deftp {Data Type} mapped-device
  4852. Objects of this type represent device mappings that will be made when
  4853. the system boots up.
  4854. @table @code
  4855. @item source
  4856. This string specifies the name of the block device to be mapped, such as
  4857. @code{"/dev/sda3"}.
  4858. @item target
  4859. This string specifies the name of the mapping to be established. For
  4860. example, specifying @code{"my-partition"} will lead to the creation of
  4861. the @code{"/dev/mapper/my-partition"} device.
  4862. @item type
  4863. This must be a @code{mapped-device-kind} object, which specifies how
  4864. @var{source} is mapped to @var{target}.
  4865. @end table
  4866. @end deftp
  4867. @defvr {Scheme Variable} luks-device-mapping
  4868. This defines LUKS block device encryption using the @command{cryptsetup}
  4869. command, from the same-named package. This relies on the
  4870. @code{dm-crypt} Linux kernel module.
  4871. @end defvr
  4872. @node User Accounts
  4873. @subsection User Accounts
  4874. User accounts and groups are entirely managed through the
  4875. @code{operating-system} declaration. They are specified with the
  4876. @code{user-account} and @code{user-group} forms:
  4877. @example
  4878. (user-account
  4879. (name "alice")
  4880. (group "users")
  4881. (supplementary-groups '("wheel" ;allow use of sudo, etc.
  4882. "audio" ;sound card
  4883. "video" ;video devices such as webcams
  4884. "cdrom")) ;the good ol' CD-ROM
  4885. (comment "Bob's sister")
  4886. (home-directory "/home/alice"))
  4887. @end example
  4888. When booting or upon completion of @command{guix system reconfigure},
  4889. the system ensures that only the user accounts and groups specified in
  4890. the @code{operating-system} declaration exist, and with the specified
  4891. properties. Thus, account or group creations or modifications made by
  4892. directly invoking commands such as @command{useradd} are lost upon
  4893. reconfiguration or reboot. This ensures that the system remains exactly
  4894. as declared.
  4895. @deftp {Data Type} user-account
  4896. Objects of this type represent user accounts. The following members may
  4897. be specified:
  4898. @table @asis
  4899. @item @code{name}
  4900. The name of the user account.
  4901. @item @code{group}
  4902. This is the name (a string) or identifier (a number) of the user group
  4903. this account belongs to.
  4904. @item @code{supplementary-groups} (default: @code{'()})
  4905. Optionally, this can be defined as a list of group names that this
  4906. account belongs to.
  4907. @item @code{uid} (default: @code{#f})
  4908. This is the user ID for this account (a number), or @code{#f}. In the
  4909. latter case, a number is automatically chosen by the system when the
  4910. account is created.
  4911. @item @code{comment} (default: @code{""})
  4912. A comment about the account, such as the account's owner full name.
  4913. @item @code{home-directory}
  4914. This is the name of the home directory for the account.
  4915. @item @code{shell} (default: Bash)
  4916. This is a G-expression denoting the file name of a program to be used as
  4917. the shell (@pxref{G-Expressions}).
  4918. @item @code{system?} (default: @code{#f})
  4919. This Boolean value indicates whether the account is a ``system''
  4920. account. System accounts are sometimes treated specially; for instance,
  4921. graphical login managers do not list them.
  4922. @anchor{user-account-password}
  4923. @item @code{password} (default: @code{#f})
  4924. You would normally leave this field to @code{#f}, initialize user
  4925. passwords as @code{root} with the @command{passwd} command, and then let
  4926. users change it with @command{passwd}. Passwords set with
  4927. @command{passwd} are of course preserved across reboot and
  4928. reconfiguration.
  4929. If you @emph{do} want to have a preset password for an account, then
  4930. this field must contain the encrypted password, as a string.
  4931. @xref{crypt,,, libc, The GNU C Library Reference Manual}, for more information
  4932. on password encryption, and @ref{Encryption,,, guile, GNU Guile Reference
  4933. Manual}, for information on Guile's @code{crypt} procedure.
  4934. @end table
  4935. @end deftp
  4936. User group declarations are even simpler:
  4937. @example
  4938. (user-group (name "students"))
  4939. @end example
  4940. @deftp {Data Type} user-group
  4941. This type is for, well, user groups. There are just a few fields:
  4942. @table @asis
  4943. @item @code{name}
  4944. The group's name.
  4945. @item @code{id} (default: @code{#f})
  4946. The group identifier (a number). If @code{#f}, a new number is
  4947. automatically allocated when the group is created.
  4948. @item @code{system?} (default: @code{#f})
  4949. This Boolean value indicates whether the group is a ``system'' group.
  4950. System groups have low numerical IDs.
  4951. @item @code{password} (default: @code{#f})
  4952. What, user groups can have a password? Well, apparently yes. Unless
  4953. @code{#f}, this field specifies the group's password.
  4954. @end table
  4955. @end deftp
  4956. For convenience, a variable lists all the basic user groups one may
  4957. expect:
  4958. @defvr {Scheme Variable} %base-groups
  4959. This is the list of basic user groups that users and/or packages expect
  4960. to be present on the system. This includes groups such as ``root'',
  4961. ``wheel'', and ``users'', as well as groups used to control access to
  4962. specific devices such as ``audio'', ``disk'', and ``cdrom''.
  4963. @end defvr
  4964. @defvr {Scheme Variable} %base-user-accounts
  4965. This is the list of basic system accounts that programs may expect to
  4966. find on a GNU/Linux system, such as the ``nobody'' account.
  4967. Note that the ``root'' account is not included here. It is a
  4968. special-case and is automatically added whether or not it is specified.
  4969. @end defvr
  4970. @node Locales
  4971. @subsection Locales
  4972. @cindex locale
  4973. A @dfn{locale} defines cultural conventions for a particular language
  4974. and region of the world (@pxref{Locales,,, libc, The GNU C Library
  4975. Reference Manual}). Each locale has a name that typically has the form
  4976. @code{@var{language}_@var{territory}.@var{codeset}}---e.g.,
  4977. @code{fr_LU.utf8} designates the locale for the French language, with
  4978. cultural conventions from Luxembourg, and using the UTF-8 encoding.
  4979. @cindex locale definition
  4980. Usually, you will want to specify the default locale for the machine
  4981. using the @code{locale} field of the @code{operating-system} declaration
  4982. (@pxref{operating-system Reference, @code{locale}}).
  4983. That locale must be among the @dfn{locale definitions} that are known to
  4984. the system---and these are specified in the @code{locale-definitions}
  4985. slot of @code{operating-system}. The default value includes locale
  4986. definition for some widely used locales, but not for all the available
  4987. locales, in order to save space.
  4988. If the locale specified in the @code{locale} field is not among the
  4989. definitions listed in @code{locale-definitions}, @command{guix system}
  4990. raises an error. In that case, you should add the locale definition to
  4991. the @code{locale-definitions} field. For instance, to add the North
  4992. Frisian locale for Germany, the value of that field may be:
  4993. @example
  4994. (cons (locale-definition
  4995. (name "fy_DE.utf8") (source "fy_DE"))
  4996. %default-locale-definitions)
  4997. @end example
  4998. Likewise, to save space, one might want @code{locale-definitions} to
  4999. list only the locales that are actually used, as in:
  5000. @example
  5001. (list (locale-definition
  5002. (name "ja_JP.eucjp") (source "ja_JP")
  5003. (charset "EUC-JP")))
  5004. @end example
  5005. @vindex LOCPATH
  5006. The compiled locale definitions are available at
  5007. @file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc
  5008. version, which is the default location where the GNU@tie{}libc provided
  5009. by Guix looks for locale data. This can be overridden using the
  5010. @code{LOCPATH} environment variable (@pxref{locales-and-locpath,
  5011. @code{LOCPATH} and locale packages}).
  5012. The @code{locale-definition} form is provided by the @code{(gnu system
  5013. locale)} module. Details are given below.
  5014. @deftp {Data Type} locale-definition
  5015. This is the data type of a locale definition.
  5016. @table @asis
  5017. @item @code{name}
  5018. The name of the locale. @xref{Locale Names,,, libc, The GNU C Library
  5019. Reference Manual}, for more information on locale names.
  5020. @item @code{source}
  5021. The name of the source for that locale. This is typically the
  5022. @code{@var{language}_@var{territory}} part of the locale name.
  5023. @item @code{charset} (default: @code{"UTF-8"})
  5024. The ``character set'' or ``code set'' for that locale,
  5025. @uref{http://www.iana.org/assignments/character-sets, as defined by
  5026. IANA}.
  5027. @end table
  5028. @end deftp
  5029. @defvr {Scheme Variable} %default-locale-definitions
  5030. An arbitrary list of commonly used UTF-8 locales, used as the default
  5031. value of the @code{locale-definitions} field of @code{operating-system}
  5032. declarations.
  5033. @cindex locale name
  5034. @cindex normalized codeset in locale names
  5035. These locale definitions use the @dfn{normalized codeset} for the part
  5036. that follows the dot in the name (@pxref{Using gettextized software,
  5037. normalized codeset,, libc, The GNU C Library Reference Manual}). So for
  5038. instance it has @code{uk_UA.utf8} but @emph{not}, say,
  5039. @code{uk_UA.UTF-8}.
  5040. @end defvr
  5041. @subsubsection Locale Data Compatibility Considerations
  5042. @cindex incompatibility, of locale data
  5043. @code{operating-system} declarations provide a @code{locale-libcs} field
  5044. to specify the GNU@tie{}libc packages that are used to compile locale
  5045. declarations (@pxref{operating-system Reference}). ``Why would I
  5046. care?'', you may ask. Well, it turns out that the binary format of
  5047. locale data is occasionally incompatible from one libc version to
  5048. another.
  5049. @c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html>
  5050. @c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>.
  5051. For instance, a program linked against libc version 2.21 is unable to
  5052. read locale data produced with libc 2.22; worse, that program
  5053. @emph{aborts} instead of simply ignoring the incompatible locale
  5054. data@footnote{Versions 2.23 and later of GNU@tie{}libc will simply skip
  5055. the incompatible locale data, which is already an improvement.}.
  5056. Similarly, a program linked against libc 2.22 can read most, but not
  5057. all, the locale data from libc 2.21 (specifically, @code{LC_COLLATE}
  5058. data is incompatible); thus calls to @code{setlocale} may fail, but
  5059. programs will not abort.
  5060. The ``problem'' in GuixSD is that users have a lot of freedom: They can
  5061. choose whether and when to upgrade software in their profiles, and might
  5062. be using a libc version different from the one the system administrator
  5063. used to build the system-wide locale data.
  5064. Fortunately, unprivileged users can also install their own locale data
  5065. and define @var{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath,
  5066. @code{GUIX_LOCPATH} and locale packages}).
  5067. Still, it is best if the system-wide locale data at
  5068. @file{/run/current-system/locale} is built for all the libc versions
  5069. actually in use on the system, so that all the programs can access
  5070. it---this is especially crucial on a multi-user system. To do that, the
  5071. administrator can specify several libc packages in the
  5072. @code{locale-libcs} field of @code{operating-system}:
  5073. @example
  5074. (use-package-modules base)
  5075. (operating-system
  5076. ;; @dots{}
  5077. (locale-libcs (list glibc-2.21 (canonical-package glibc))))
  5078. @end example
  5079. This example would lead to a system containing locale definitions for
  5080. both libc 2.21 and the current version of libc in
  5081. @file{/run/current-system/locale}.
  5082. @node Services
  5083. @subsection Services
  5084. @cindex system services
  5085. An important part of preparing an @code{operating-system} declaration is
  5086. listing @dfn{system services} and their configuration (@pxref{Using the
  5087. Configuration System}). System services are typically daemons launched
  5088. when the system boots, or other actions needed at that time---e.g.,
  5089. configuring network access.
  5090. Services are managed by GNU@tie{}dmd (@pxref{Introduction,,, dmd, GNU
  5091. dmd Manual}). On a running system, the @command{deco} command allows
  5092. you to list the available services, show their status, start and stop
  5093. them, or do other specific operations (@pxref{Jump Start,,, dmd, GNU dmd
  5094. Manual}). For example:
  5095. @example
  5096. # deco status dmd
  5097. @end example
  5098. The above command, run as @code{root}, lists the currently defined
  5099. services. The @command{deco doc} command shows a synopsis of the given
  5100. service:
  5101. @example
  5102. # deco doc nscd
  5103. Run libc's name service cache daemon (nscd).
  5104. @end example
  5105. The @command{start}, @command{stop}, and @command{restart} sub-commands
  5106. have the effect you would expect. For instance, the commands below stop
  5107. the nscd service and restart the Xorg display server:
  5108. @example
  5109. # deco stop nscd
  5110. Service nscd has been stopped.
  5111. # deco restart xorg-server
  5112. Service xorg-server has been stopped.
  5113. Service xorg-server has been started.
  5114. @end example
  5115. The following sections document the available services, starting with
  5116. the core services, that may be used in an @code{operating-system}
  5117. declaration.
  5118. @menu
  5119. * Base Services:: Essential system services.
  5120. * Networking Services:: Network setup, SSH daemon, etc.
  5121. * X Window:: Graphical display.
  5122. * Desktop Services:: D-Bus and desktop services.
  5123. * Database Services:: SQL databases.
  5124. * Mail Services:: IMAP, POP3, SMTP, and all that.
  5125. * Web Services:: Web servers.
  5126. * Various Services:: Other services.
  5127. @end menu
  5128. @node Base Services
  5129. @subsubsection Base Services
  5130. The @code{(gnu services base)} module provides definitions for the basic
  5131. services that one expects from the system. The services exported by
  5132. this module are listed below.
  5133. @defvr {Scheme Variable} %base-services
  5134. This variable contains a list of basic services (@pxref{Service Types
  5135. and Services}, for more information on service objects) one would
  5136. expect from the system: a login service (mingetty) on each tty, syslogd,
  5137. libc's name service cache daemon (nscd), the udev device manager, and
  5138. more.
  5139. This is the default value of the @code{services} field of
  5140. @code{operating-system} declarations. Usually, when customizing a
  5141. system, you will want to append services to @var{%base-services}, like
  5142. this:
  5143. @example
  5144. (cons* (avahi-service) (lsh-service) %base-services)
  5145. @end example
  5146. @end defvr
  5147. @deffn {Scheme Procedure} host-name-service @var{name}
  5148. Return a service that sets the host name to @var{name}.
  5149. @end deffn
  5150. @deffn {Scheme Procedure} mingetty-service @var{config}
  5151. Return a service to run mingetty according to @var{config}, a
  5152. @code{<mingetty-configuration>} object, which specifies the tty to run, among
  5153. other things.
  5154. @end deffn
  5155. @deftp {Data Type} mingetty-configuration
  5156. This is the data type representing the configuration of Mingetty, which
  5157. implements console log-in.
  5158. @table @asis
  5159. @item @code{tty}
  5160. The name of the console this Mingetty runs on---e.g., @code{"tty1"}.
  5161. @item @code{motd}
  5162. A file-like object containing the ``message of the day''.
  5163. @item @code{auto-login} (default: @code{#f})
  5164. When true, this field must be a string denoting the user name under
  5165. which the system automatically logs in. When it is @code{#f}, a
  5166. user name and password must be entered to log in.
  5167. @item @code{login-program} (default: @code{#f})
  5168. This must be either @code{#f}, in which case the default log-in program
  5169. is used (@command{login} from the Shadow tool suite), or a gexp denoting
  5170. the name of the log-in program.
  5171. @item @code{login-pause?} (default: @code{#f})
  5172. When set to @code{#t} in conjunction with @var{auto-login}, the user
  5173. will have to press a key before the log-in shell is launched.
  5174. @item @code{mingetty} (default: @var{mingetty})
  5175. The Mingetty package to use.
  5176. @end table
  5177. @end deftp
  5178. @cindex name service cache daemon
  5179. @cindex nscd
  5180. @deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @
  5181. [#:name-services '()]
  5182. Return a service that runs libc's name service cache daemon (nscd) with the
  5183. given @var{config}---an @code{<nscd-configuration>} object. @xref{Name
  5184. Service Switch}, for an example.
  5185. @end deffn
  5186. @defvr {Scheme Variable} %nscd-default-configuration
  5187. This is the default @code{<nscd-configuration>} value (see below) used
  5188. by @code{nscd-service}. This uses the caches defined by
  5189. @var{%nscd-default-caches}; see below.
  5190. @end defvr
  5191. @deftp {Data Type} nscd-configuration
  5192. This is the type representing the name service cache daemon (nscd)
  5193. configuration.
  5194. @table @asis
  5195. @item @code{name-services} (default: @code{'()})
  5196. List of packages denoting @dfn{name services} that must be visible to
  5197. the nscd---e.g., @code{(list @var{nss-mdns})}.
  5198. @item @code{glibc} (default: @var{glibc})
  5199. Package object denoting the GNU C Library providing the @command{nscd}
  5200. command.
  5201. @item @code{log-file} (default: @code{"/var/log/nscd.log"})
  5202. Name of nscd's log file. This is where debugging output goes when
  5203. @code{debug-level} is strictly positive.
  5204. @item @code{debug-level} (default: @code{0})
  5205. Integer denoting the debugging levels. Higher numbers mean more
  5206. debugging output is logged.
  5207. @item @code{caches} (default: @var{%nscd-default-caches})
  5208. List of @code{<nscd-cache>} objects denoting things to be cached; see
  5209. below.
  5210. @end table
  5211. @end deftp
  5212. @deftp {Data Type} nscd-cache
  5213. Data type representing a cache database of nscd and its parameters.
  5214. @table @asis
  5215. @item @code{database}
  5216. This is a symbol representing the name of the database to be cached.
  5217. Valid values are @code{passwd}, @code{group}, @code{hosts}, and
  5218. @code{services}, which designate the corresponding NSS database
  5219. (@pxref{NSS Basics,,, libc, The GNU C Library Reference Manual}).
  5220. @item @code{positive-time-to-live}
  5221. @itemx @code{negative-time-to-live} (default: @code{20})
  5222. A number representing the number of seconds during which a positive or
  5223. negative lookup result remains in cache.
  5224. @item @code{check-files?} (default: @code{#t})
  5225. Whether to check for updates of the files corresponding to
  5226. @var{database}.
  5227. For instance, when @var{database} is @code{hosts}, setting this flag
  5228. instructs nscd to check for updates in @file{/etc/hosts} and to take
  5229. them into account.
  5230. @item @code{persistent?} (default: @code{#t})
  5231. Whether the cache should be stored persistently on disk.
  5232. @item @code{shared?} (default: @code{#t})
  5233. Whether the cache should be shared among users.
  5234. @item @code{max-database-size} (default: 32@tie{}MiB)
  5235. Maximum size in bytes of the database cache.
  5236. @c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert
  5237. @c settings, so leave them out.
  5238. @end table
  5239. @end deftp
  5240. @defvr {Scheme Variable} %nscd-default-caches
  5241. List of @code{<nscd-cache>} objects used by default by
  5242. @code{nscd-configuration} (see above.)
  5243. It enables persistent and aggressive caching of service and host name
  5244. lookups. The latter provides better host name lookup performance,
  5245. resilience in the face of unreliable name servers, and also better
  5246. privacy---often the result of host name lookups is in local cache, so
  5247. external name servers do not even need to be queried.
  5248. @end defvr
  5249. @deffn {Scheme Procedure} syslog-service [#:config-file #f]
  5250. Return a service that runs @code{syslogd}. If configuration file name
  5251. @var{config-file} is not specified, use some reasonable default
  5252. settings.
  5253. @end deffn
  5254. @anchor{guix-configuration-type}
  5255. @deftp {Data Type} guix-configuration
  5256. This data type represents the configuration of the Guix build daemon.
  5257. @xref{Invoking guix-daemon}, for more information.
  5258. @table @asis
  5259. @item @code{guix} (default: @var{guix})
  5260. The Guix package to use.
  5261. @item @code{build-group} (default: @code{"guixbuild"})
  5262. Name of the group for build user accounts.
  5263. @item @code{build-accounts} (default: @code{10})
  5264. Number of build user accounts to create.
  5265. @item @code{authorize-key?} (default: @code{#t})
  5266. Whether to authorize the substitute key for @code{hydra.gnu.org}
  5267. (@pxref{Substitutes}).
  5268. @item @code{use-substitutes?} (default: @code{#t})
  5269. Whether to use substitutes.
  5270. @item @code{substitute-urls} (default: @var{%default-substitute-urls})
  5271. The list of URLs where to look for substitutes by default.
  5272. @item @code{extra-options} (default: @code{'()})
  5273. List of extra command-line options for @command{guix-daemon}.
  5274. @item @code{lsof} (default: @var{lsof})
  5275. @itemx @code{lsh} (default: @var{lsh})
  5276. The lsof and lsh packages to use.
  5277. @end table
  5278. @end deftp
  5279. @deffn {Scheme Procedure} guix-service @var{config}
  5280. Return a service that runs the Guix build daemon according to
  5281. @var{config}.
  5282. @end deffn
  5283. @deffn {Scheme Procedure} udev-service [#:udev udev]
  5284. Run @var{udev}, which populates the @file{/dev} directory dynamically.
  5285. @end deffn
  5286. @deffn {Scheme Procedure} console-keymap-service @var{file}
  5287. Return a service to load console keymap from @var{file} using
  5288. @command{loadkeys} command.
  5289. @end deffn
  5290. @deffn {Scheme Procedure} gpm-service-type [#:gpm @var{gpm}] @
  5291. [#:options]
  5292. Run @var{gpm}, the general-purpose mouse daemon, with the given
  5293. command-line @var{options}. GPM allows users to use the mouse in the console,
  5294. notably to select, copy, and paste text. The default value of @var{options}
  5295. uses the @code{ps2} protocol, which works for both USB and PS/2 mice.
  5296. This service is not part of @var{%base-services}.
  5297. @end deffn
  5298. @anchor{guix-publish-service}
  5299. @deffn {Scheme Procedure} guix-publish-service [#:guix @var{guix}] @
  5300. [#:port 80] [#:host "localhost"]
  5301. Return a service that runs @command{guix publish} listening on @var{host}
  5302. and @var{port} (@pxref{Invoking guix publish}).
  5303. This assumes that @file{/etc/guix} already contains a signing key pair as
  5304. created by @command{guix archive --generate-key} (@pxref{Invoking guix
  5305. archive}). If that is not the case, the service will fail to start.
  5306. @end deffn
  5307. @node Networking Services
  5308. @subsubsection Networking Services
  5309. The @code{(gnu services networking)} module provides services to configure
  5310. the network interface.
  5311. @cindex DHCP, networking service
  5312. @deffn {Scheme Procedure} dhcp-client-service [#:dhcp @var{isc-dhcp}]
  5313. Return a service that runs @var{dhcp}, a Dynamic Host Configuration
  5314. Protocol (DHCP) client, on all the non-loopback network interfaces.
  5315. @end deffn
  5316. @deffn {Scheme Procedure} static-networking-service @var{interface} @var{ip} @
  5317. [#:gateway #f] [#:name-services @code{'()}]
  5318. Return a service that starts @var{interface} with address @var{ip}. If
  5319. @var{gateway} is true, it must be a string specifying the default network
  5320. gateway.
  5321. @end deffn
  5322. @cindex wicd
  5323. @cindex network management
  5324. @deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}]
  5325. Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network
  5326. management daemon that aims to simplify wired and wireless networking.
  5327. This service adds the @var{wicd} package to the global profile, providing
  5328. several commands to interact with the daemon and configure networking:
  5329. @command{wicd-client}, a graphical user interface, and the @command{wicd-cli}
  5330. and @command{wicd-curses} user interfaces.
  5331. @end deffn
  5332. @cindex NetworkManager
  5333. @deffn {Scheme Procedure} network-manager-service @
  5334. [#:network-manager @var{network-manager}]
  5335. Return a service that runs NetworkManager, a network connection manager
  5336. that attempting to keep active network connectivity when available.
  5337. @end deffn
  5338. @deffn {Scheme Procedure} ntp-service [#:ntp @var{ntp}] @
  5339. [#:name-service @var{%ntp-servers}]
  5340. Return a service that runs the daemon from @var{ntp}, the
  5341. @uref{http://www.ntp.org, Network Time Protocol package}. The daemon will
  5342. keep the system clock synchronized with that of @var{servers}.
  5343. @end deffn
  5344. @defvr {Scheme Variable} %ntp-servers
  5345. List of host names used as the default NTP servers.
  5346. @end defvr
  5347. @deffn {Scheme Procedure} tor-service [@var{config-file}] [#:tor @var{tor}]
  5348. Return a service to run the @uref{https://torproject.org, Tor} anonymous
  5349. networking daemon.
  5350. The daemon runs as the @code{tor} unprivileged user. It is passed
  5351. @var{config-file}, a file-like object, with an additional @code{User tor} line
  5352. and lines for hidden services added via @code{tor-hidden-service}. Run
  5353. @command{man tor} for information about the configuration file.
  5354. @end deffn
  5355. @deffn {Scheme Procedure} tor-hidden-service @var{name} @var{mapping}
  5356. Define a new Tor @dfn{hidden service} called @var{name} and implementing
  5357. @var{mapping}. @var{mapping} is a list of port/host tuples, such as:
  5358. @example
  5359. '((22 \"127.0.0.1:22\")
  5360. (80 \"127.0.0.1:8080\"))
  5361. @end example
  5362. In this example, port 22 of the hidden service is mapped to local port 22, and
  5363. port 80 is mapped to local port 8080.
  5364. This creates a @file{/var/lib/tor/hidden-services/@var{name}} directory, where
  5365. the @file{hostname} file contains the @code{.onion} host name for the hidden
  5366. service.
  5367. See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor
  5368. project's documentation} for more information.
  5369. @end deffn
  5370. @deffn {Scheme Procedure} bitlbee-service [#:bitlbee bitlbee] @
  5371. [#:interface "127.0.0.1"] [#:port 6667] @
  5372. [#:extra-settings ""]
  5373. Return a service that runs @url{http://bitlbee.org,BitlBee}, a daemon that
  5374. acts as a gateway between IRC and chat networks.
  5375. The daemon will listen to the interface corresponding to the IP address
  5376. specified in @var{interface}, on @var{port}. @code{127.0.0.1} means that only
  5377. local clients can connect, whereas @code{0.0.0.0} means that connections can
  5378. come from any networking interface.
  5379. In addition, @var{extra-settings} specifies a string to append to the
  5380. configuration file.
  5381. @end deffn
  5382. Furthermore, @code{(gnu services ssh)} provides the following service.
  5383. @deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
  5384. [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @
  5385. [#:allow-empty-passwords? #f] [#:root-login? #f] @
  5386. [#:syslog-output? #t] [#:x11-forwarding? #t] @
  5387. [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @
  5388. [#:public-key-authentication? #t] [#:initialize? #t]
  5389. Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}.
  5390. @var{host-key} must designate a file containing the host key, and readable
  5391. only by root.
  5392. When @var{daemonic?} is true, @command{lshd} will detach from the
  5393. controlling terminal and log its output to syslogd, unless one sets
  5394. @var{syslog-output?} to false. Obviously, it also makes lsh-service
  5395. depend on existence of syslogd service. When @var{pid-file?} is true,
  5396. @command{lshd} writes its PID to the file called @var{pid-file}.
  5397. When @var{initialize?} is true, automatically create the seed and host key
  5398. upon service activation if they do not exist yet. This may take long and
  5399. require interaction.
  5400. When @var{initialize?} is false, it is up to the user to initialize the
  5401. randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
  5402. a key pair with the private key stored in file @var{host-key} (@pxref{lshd
  5403. basics,,, lsh, LSH Manual}).
  5404. When @var{interfaces} is empty, lshd listens for connections on all the
  5405. network interfaces; otherwise, @var{interfaces} must be a list of host names
  5406. or addresses.
  5407. @var{allow-empty-passwords?} specifies whether to accept log-ins with empty
  5408. passwords, and @var{root-login?} specifies whether to accept log-ins as
  5409. root.
  5410. The other options should be self-descriptive.
  5411. @end deffn
  5412. @defvr {Scheme Variable} %facebook-host-aliases
  5413. This variable contains a string for use in @file{/etc/hosts}
  5414. (@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each
  5415. line contains a entry that maps a known server name of the Facebook
  5416. on-line service---e.g., @code{www.facebook.com}---to the local
  5417. host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}.
  5418. This variable is typically used in the @code{hosts-file} field of an
  5419. @code{operating-system} declaration (@pxref{operating-system Reference,
  5420. @file{/etc/hosts}}):
  5421. @example
  5422. (use-modules (gnu) (guix))
  5423. (operating-system
  5424. (host-name "mymachine")
  5425. ;; ...
  5426. (hosts-file
  5427. ;; Create a /etc/hosts file with aliases for "localhost"
  5428. ;; and "mymachine", as well as for Facebook servers.
  5429. (plain-file "hosts"
  5430. (string-append (local-host-aliases host-name)
  5431. %facebook-host-aliases))))
  5432. @end example
  5433. This mechanism can prevent programs running locally, such as Web
  5434. browsers, from accessing Facebook.
  5435. @end defvr
  5436. The @code{(gnu services avahi)} provides the following definition.
  5437. @deffn {Scheme Procedure} avahi-service [#:avahi @var{avahi}] @
  5438. [#:host-name #f] [#:publish? #t] [#:ipv4? #t] @
  5439. [#:ipv6? #t] [#:wide-area? #f] @
  5440. [#:domains-to-browse '()]
  5441. Return a service that runs @command{avahi-daemon}, a system-wide
  5442. mDNS/DNS-SD responder that allows for service discovery and
  5443. "zero-configuration" host name lookups (see @uref{http://avahi.org/}), and
  5444. extends the name service cache daemon (nscd) so that it can resolve
  5445. @code{.local} host names using
  5446. @uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. Additionally,
  5447. add the @var{avahi} package to the system profile so that commands such as
  5448. @command{avahi-browse} are directly usable.
  5449. If @var{host-name} is different from @code{#f}, use that as the host name to
  5450. publish for this machine; otherwise, use the machine's actual host name.
  5451. When @var{publish?} is true, publishing of host names and services is allowed;
  5452. in particular, avahi-daemon will publish the machine's host name and IP
  5453. address via mDNS on the local network.
  5454. When @var{wide-area?} is true, DNS-SD over unicast DNS is enabled.
  5455. Boolean values @var{ipv4?} and @var{ipv6?} determine whether to use IPv4/IPv6
  5456. sockets.
  5457. @end deffn
  5458. @node X Window
  5459. @subsubsection X Window
  5460. Support for the X Window graphical display system---specifically
  5461. Xorg---is provided by the @code{(gnu services xorg)} module. Note that
  5462. there is no @code{xorg-service} procedure. Instead, the X server is
  5463. started by the @dfn{login manager}, currently SLiM.
  5464. @deffn {Scheme Procedure} slim-service [#:allow-empty-passwords? #f] @
  5465. [#:auto-login? #f] [#:default-user ""] [#:startx] @
  5466. [#:theme @var{%default-slim-theme}] @
  5467. [#:theme-name @var{%default-slim-theme-name}]
  5468. Return a service that spawns the SLiM graphical login manager, which in
  5469. turn starts the X display server with @var{startx}, a command as returned by
  5470. @code{xorg-start-command}.
  5471. @cindex X session
  5472. SLiM automatically looks for session types described by the @file{.desktop}
  5473. files in @file{/run/current-system/profile/share/xsessions} and allows users
  5474. to choose a session from the log-in screen using @kbd{F1}. Packages such as
  5475. @var{xfce}, @var{sawfish}, and @var{ratpoison} provide @file{.desktop} files;
  5476. adding them to the system-wide set of packages automatically makes them
  5477. available at the log-in screen.
  5478. In addition, @file{~/.xsession} files are honored. When available,
  5479. @file{~/.xsession} must be an executable that starts a window manager
  5480. and/or other X clients.
  5481. When @var{allow-empty-passwords?} is true, allow logins with an empty
  5482. password. When @var{auto-login?} is true, log in automatically as
  5483. @var{default-user}.
  5484. If @var{theme} is @code{#f}, the use the default log-in theme; otherwise
  5485. @var{theme} must be a gexp denoting the name of a directory containing the
  5486. theme to use. In that case, @var{theme-name} specifies the name of the
  5487. theme.
  5488. @end deffn
  5489. @defvr {Scheme Variable} %default-theme
  5490. @defvrx {Scheme Variable} %default-theme-name
  5491. The G-Expression denoting the default SLiM theme and its name.
  5492. @end defvr
  5493. @deffn {Scheme Procedure} xorg-start-command [#:guile] @
  5494. [#:configuration-file #f] [#:xorg-server @var{xorg-server}]
  5495. Return a derivation that builds a @var{guile} script to start the X server
  5496. from @var{xorg-server}. @var{configuration-file} is the server configuration
  5497. file or a derivation that builds it; when omitted, the result of
  5498. @code{xorg-configuration-file} is used.
  5499. Usually the X server is started by a login manager.
  5500. @end deffn
  5501. @deffn {Scheme Procedure} xorg-configuration-file @
  5502. [#:drivers '()] [#:resolutions '()] [#:extra-config '()]
  5503. Return a configuration file for the Xorg server containing search paths for
  5504. all the common drivers.
  5505. @var{drivers} must be either the empty list, in which case Xorg chooses a
  5506. graphics driver automatically, or a list of driver names that will be tried in
  5507. this order---e.g., @code{(\"modesetting\" \"vesa\")}.
  5508. Likewise, when @var{resolutions} is the empty list, Xorg chooses an
  5509. appropriate screen resolution; otherwise, it must be a list of
  5510. resolutions---e.g., @code{((1024 768) (640 480))}.
  5511. Last, @var{extra-config} is a list of strings or objects appended to the
  5512. @code{text-file*} argument list. It is used to pass extra text to be added
  5513. verbatim to the configuration file.
  5514. @end deffn
  5515. @deffn {Scheme Procedure} screen-locker-service @var{package} [@var{name}]
  5516. Add @var{package}, a package for a screen-locker or screen-saver whose
  5517. command is @var{program}, to the set of setuid programs and add a PAM entry
  5518. for it. For example:
  5519. @lisp
  5520. (screen-locker-service xlockmore "xlock")
  5521. @end lisp
  5522. makes the good ol' XlockMore usable.
  5523. @end deffn
  5524. @node Desktop Services
  5525. @subsubsection Desktop Services
  5526. The @code{(gnu services desktop)} module provides services that are
  5527. usually useful in the context of a ``desktop'' setup---that is, on a
  5528. machine running a graphical display server, possibly with graphical user
  5529. interfaces, etc.
  5530. To simplify things, the module defines a variable containing the set of
  5531. services that users typically expect on a machine with a graphical
  5532. environment and networking:
  5533. @defvr {Scheme Variable} %desktop-services
  5534. This is a list of services that builds upon @var{%base-services} and
  5535. adds or adjust services for a typical ``desktop'' setup.
  5536. In particular, it adds a graphical login manager (@pxref{X Window,
  5537. @code{slim-service}}), screen lockers,
  5538. a network management tool (@pxref{Networking
  5539. Services, @code{wicd-service}}), energy and color management services,
  5540. the @code{elogind} login and seat manager, the Polkit privilege service,
  5541. the GeoClue location service, an NTP client (@pxref{Networking
  5542. Services}), the Avahi daemon, and has the name service switch service
  5543. configured to be able to use @code{nss-mdns} (@pxref{Name Service
  5544. Switch, mDNS}).
  5545. @end defvr
  5546. The @var{%desktop-services} variable can be used as the @code{services}
  5547. field of an @code{operating-system} declaration (@pxref{operating-system
  5548. Reference, @code{services}}).
  5549. The actual service definitions provided by @code{(gnu services dbus)}
  5550. and @code{(gnu services desktop)} are described below.
  5551. @deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()]
  5552. Return a service that runs the ``system bus'', using @var{dbus}, with
  5553. support for @var{services}.
  5554. @uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication
  5555. facility. Its system bus is used to allow system services to communicate
  5556. and be notified of system-wide events.
  5557. @var{services} must be a list of packages that provide an
  5558. @file{etc/dbus-1/system.d} directory containing additional D-Bus configuration
  5559. and policy files. For example, to allow avahi-daemon to use the system bus,
  5560. @var{services} must be equal to @code{(list avahi)}.
  5561. @end deffn
  5562. @deffn {Scheme Procedure} elogind-service [#:config @var{config}]
  5563. Return a service that runs the @code{elogind} login and
  5564. seat management daemon. @uref{https://github.com/andywingo/elogind,
  5565. Elogind} exposes a D-Bus interface that can be used to know which users
  5566. are logged in, know what kind of sessions they have open, suspend the
  5567. system, inhibit system suspend, reboot the system, and other tasks.
  5568. Elogind handles most system-level power events for a computer, for
  5569. example suspending the system when a lid is closed, or shutting it down
  5570. when the power button is pressed.
  5571. The @var{config} keyword argument specifies the configuration for
  5572. elogind, and should be the result of a @code{(elogind-configuration
  5573. (@var{parameter} @var{value})...)} invocation. Available parameters and
  5574. their default values are:
  5575. @table @code
  5576. @item kill-user-processes?
  5577. @code{#f}
  5578. @item kill-only-users
  5579. @code{()}
  5580. @item kill-exclude-users
  5581. @code{("root")}
  5582. @item inhibit-delay-max-seconds
  5583. @code{5}
  5584. @item handle-power-key
  5585. @code{poweroff}
  5586. @item handle-suspend-key
  5587. @code{suspend}
  5588. @item handle-hibernate-key
  5589. @code{hibernate}
  5590. @item handle-lid-switch
  5591. @code{suspend}
  5592. @item handle-lid-switch-docked
  5593. @code{ignore}
  5594. @item power-key-ignore-inhibited?
  5595. @code{#f}
  5596. @item suspend-key-ignore-inhibited?
  5597. @code{#f}
  5598. @item hibernate-key-ignore-inhibited?
  5599. @code{#f}
  5600. @item lid-switch-ignore-inhibited?
  5601. @code{#t}
  5602. @item holdoff-timeout-seconds
  5603. @code{30}
  5604. @item idle-action
  5605. @code{ignore}
  5606. @item idle-action-seconds
  5607. @code{(* 30 60)}
  5608. @item runtime-directory-size-percent
  5609. @code{10}
  5610. @item runtime-directory-size
  5611. @code{#f}
  5612. @item remove-ipc?
  5613. @code{#t}
  5614. @item suspend-state
  5615. @code{("mem" "standby" "freeze")}
  5616. @item suspend-mode
  5617. @code{()}
  5618. @item hibernate-state
  5619. @code{("disk")}
  5620. @item hibernate-mode
  5621. @code{("platform" "shutdown")}
  5622. @item hybrid-sleep-state
  5623. @code{("disk")}
  5624. @item hybrid-sleep-mode
  5625. @code{("suspend" "platform" "shutdown")}
  5626. @end table
  5627. @end deffn
  5628. @deffn {Scheme Procedure} polkit-service @
  5629. [#:polkit @var{polkit}]
  5630. Return a service that runs the
  5631. @uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege
  5632. management service}, which allows system administrators to grant access to
  5633. privileged operations in a structured way. By querying the Polkit service, a
  5634. privileged system component can know when it should grant additional
  5635. capabilities to ordinary users. For example, an ordinary user can be granted
  5636. the capability to suspend the system if the user is logged in locally.
  5637. @end deffn
  5638. @deffn {Scheme Procedure} upower-service [#:upower @var{upower}] @
  5639. [#:watts-up-pro? #f] @
  5640. [#:poll-batteries? #t] @
  5641. [#:ignore-lid? #f] @
  5642. [#:use-percentage-for-policy? #f] @
  5643. [#:percentage-low 10] @
  5644. [#:percentage-critical 3] @
  5645. [#:percentage-action 2] @
  5646. [#:time-low 1200] @
  5647. [#:time-critical 300] @
  5648. [#:time-action 120] @
  5649. [#:critical-power-action 'hybrid-sleep]
  5650. Return a service that runs @uref{http://upower.freedesktop.org/,
  5651. @command{upowerd}}, a system-wide monitor for power consumption and battery
  5652. levels, with the given configuration settings. It implements the
  5653. @code{org.freedesktop.UPower} D-Bus interface, and is notably used by
  5654. GNOME.
  5655. @end deffn
  5656. @deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}]
  5657. Return a service for @uref{http://udisks.freedesktop.org/docs/latest/,
  5658. UDisks}, a @dfn{disk management} daemon that provides user interfaces with
  5659. notifications and ways to mount/unmount disks. Programs that talk to UDisks
  5660. include the @command{udisksctl} command, part of UDisks, and GNOME Disks.
  5661. @end deffn
  5662. @deffn {Scheme Procedure} colord-service [#:colord @var{colord}]
  5663. Return a service that runs @command{colord}, a system service with a D-Bus
  5664. interface to manage the color profiles of input and output devices such as
  5665. screens and scanners. It is notably used by the GNOME Color Manager graphical
  5666. tool. See @uref{http://www.freedesktop.org/software/colord/, the colord web
  5667. site} for more information.
  5668. @end deffn
  5669. @deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
  5670. Return an configuration allowing an application to access GeoClue
  5671. location data. @var{name} is the Desktop ID of the application, without
  5672. the @code{.desktop} part. If @var{allowed?} is true, the application
  5673. will have access to location information by default. The boolean
  5674. @var{system?} value indicates that an application is a system component
  5675. or not. Finally @var{users} is a list of UIDs of all users for which
  5676. this application is allowed location info access. An empty users list
  5677. means that all users are allowed.
  5678. @end deffn
  5679. @defvr {Scheme Variable} %standard-geoclue-applications
  5680. The standard list of well-known GeoClue application configurations,
  5681. granting authority to GNOME's date-and-time utility to ask for the
  5682. current location in order to set the time zone, and allowing the Firefox
  5683. (IceCat) and Epiphany web browsers to request location information.
  5684. Firefox and Epiphany both query the user before allowing a web page to
  5685. know the user's location.
  5686. @end defvr
  5687. @deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @
  5688. [#:whitelist '()] @
  5689. [#:wifi-geolocation-url "https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @
  5690. [#:submit-data? #f]
  5691. [#:wifi-submission-url "https://location.services.mozilla.com/v1/submit?key=geoclue"] @
  5692. [#:submission-nick "geoclue"] @
  5693. [#:applications %standard-geoclue-applications]
  5694. Return a service that runs the GeoClue location service. This service
  5695. provides a D-Bus interface to allow applications to request access to a
  5696. user's physical location, and optionally to add information to online
  5697. location databases. See
  5698. @uref{https://wiki.freedesktop.org/www/Software/GeoClue/, the GeoClue
  5699. web site} for more information.
  5700. @end deffn
  5701. @node Database Services
  5702. @subsubsection Database Services
  5703. The @code{(gnu services databases)} module provides the following service.
  5704. @deffn {Scheme Procedure} postgresql-service [#:postgresql postgresql] @
  5705. [#:config-file] [#:data-directory ``/var/lib/postgresql/data'']
  5706. Return a service that runs @var{postgresql}, the PostgreSQL database
  5707. server.
  5708. The PostgreSQL daemon loads its runtime configuration from
  5709. @var{config-file} and stores the database cluster in
  5710. @var{data-directory}.
  5711. @end deffn
  5712. @node Mail Services
  5713. @subsubsection Mail Services
  5714. The @code{(gnu services mail)} module provides Guix service definitions
  5715. for mail services. Currently the only implemented service is Dovecot,
  5716. an IMAP, POP3, and LMTP server.
  5717. Guix does not yet have a mail transfer agent (MTA), although for some
  5718. lightweight purposes the @code{esmtp} relay-only MTA may suffice. Help
  5719. is needed to properly integrate a full MTA, such as Postfix. Patches
  5720. welcome!
  5721. To add an IMAP/POP3 server to a GuixSD system, add a
  5722. @code{dovecot-service} to the operating system definition:
  5723. @deffn {Scheme Procedure} dovecot-service [#:config (dovecot-configuration)]
  5724. Return a service that runs the Dovecot IMAP/POP3/LMTP mail server.
  5725. @end deffn
  5726. By default, Dovecot doesn't need much configuration; the default
  5727. configuration object created by @code{(dovecot-configuration)} will
  5728. suffice if your mail is delivered to @code{~/Maildir}. A self-signed
  5729. certificate will be generated for TLS-protected connections, though
  5730. Dovecot will also listen on cleartext ports by default. There are a
  5731. number of options though which mail administrators might need to change,
  5732. and as is the case with other services, Guix allows the system
  5733. administrator to specify these parameters via a uniform Scheme interface.
  5734. For example, to specify that mail is located at @code{maildir~/.mail},
  5735. one would instantiate the Dovecot service like this:
  5736. @example
  5737. (dovecot-service #:config
  5738. (dovecot-configuration
  5739. (mail-location "maildir:~/.mail")))
  5740. @end example
  5741. The available configuration parameters follow. Each parameter
  5742. definition is preceded by its type; for example, @samp{string-list foo}
  5743. indicates that the @code{foo} parameter should be specified as a list of
  5744. strings. There is also a way to specify the configuration as a string,
  5745. if you have an old @code{dovecot.conf} file that you want to port over
  5746. from some other system; see the end for more details.
  5747. @c The following documentation was initially generated by
  5748. @c (generate-documentation) in (gnu services mail). Manually maintained
  5749. @c documentation is better, so we shouldn't hesitate to edit below as
  5750. @c needed. However if the change you want to make to this documentation
  5751. @c can be done in an automated way, it's probably easier to change
  5752. @c (generate-documentation) than to make it below and have to deal with
  5753. @c the churn as dovecot updates.
  5754. Available @code{dovecot-configuration} fields are:
  5755. @deftypevr {@code{dovecot-configurati