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.

5486 lines
210 KiB

  1. \input texinfo
  2. @c -*-texinfo-*-
  3. @c %**start of header
  4. @setfilename
  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 Ludovic Courtès@*
  11. Copyright @copyright{} 2013, 2014 Andreas Enge@*
  12. Copyright @copyright{} 2013 Nikita Karetnikov
  13. Permission is granted to copy, distribute and/or modify this document
  14. under the terms of the GNU Free Documentation License, Version 1.3 or
  15. any later version published by the Free Software Foundation; with no
  16. Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
  17. copy of the license is included in the section entitled ``GNU Free
  18. Documentation License''.
  19. @end copying
  20. @dircategory Package management
  21. @direntry
  22. * guix: (guix). Guix, the functional package manager.
  23. * guix package: (guix)Invoking guix package
  24. Managing packages with Guix.
  25. * guix build: (guix)Invoking guix build
  26. Building packages with Guix.
  27. * guix system: (guix)Invoking guix system
  28. Managing the operating system configuration.
  29. @end direntry
  30. @dircategory Software development
  31. @direntry
  32. * guix environment: (guix)Invoking guix environment
  33. Building development environments with Guix.
  34. @end direntry
  35. @titlepage
  36. @title GNU Guix Reference Manual
  37. @subtitle Using the GNU Guix Functional Package Manager
  38. @author Ludovic Courtès
  39. @author Andreas Enge
  40. @author Nikita Karetnikov
  41. @page
  42. @vskip 0pt plus 1filll
  43. Edition @value{EDITION} @*
  44. @value{UPDATED} @*
  45. @insertcopying
  46. @end titlepage
  47. @contents
  48. @c *********************************************************************
  49. @node Top
  50. @top GNU Guix
  51. This document describes GNU Guix version @value{VERSION}, a functional
  52. package management tool written for the GNU system.
  53. @menu
  54. * Introduction:: What is Guix about?
  55. * Installation:: Installing Guix.
  56. * Package Management:: Package installation, upgrade, etc.
  57. * Programming Interface:: Using Guix in Scheme.
  58. * Utilities:: Package management commands.
  59. * GNU Distribution:: Software for your friendly GNU system.
  60. * Contributing:: Your help needed!
  61. * Acknowledgments:: Thanks!
  62. * GNU Free Documentation License:: The license of this manual.
  63. * Concept Index:: Concepts.
  64. * Programming Index:: Data types, functions, and variables.
  65. @detailmenu
  66. --- The Detailed Node Listing ---
  67. Installation
  68. * Requirements:: Software needed to build and run Guix.
  69. * Setting Up the Daemon:: Preparing the build daemon's environment.
  70. * Invoking guix-daemon:: Running the build daemon.
  71. Setting Up the Daemon
  72. * Build Environment Setup:: Preparing the isolated build environment.
  73. * Daemon Offload Setup:: Offloading builds to remote machines.
  74. Package Management
  75. * Features:: How Guix will make your life brighter.
  76. * Invoking guix package:: Package installation, removal, etc.
  77. * Emacs Interface:: Package management from Emacs.
  78. * Substitutes:: Downloading pre-built binaries.
  79. * Packages with Multiple Outputs:: Single source package, multiple outputs.
  80. * Invoking guix gc:: Running the garbage collector.
  81. * Invoking guix pull:: Fetching the latest Guix and distribution.
  82. * Invoking guix archive:: Exporting and importing store files.
  83. Programming Interface
  84. * Defining Packages:: Defining new packages.
  85. * Build Systems:: Specifying how packages are built.
  86. * The Store:: Manipulating the package store.
  87. * Derivations:: Low-level interface to package derivations.
  88. * The Store Monad:: Purely functional interface to the store.
  89. * G-Expressions:: Manipulating build expressions.
  90. Utilities
  91. * Invoking guix build:: Building packages from the command line.
  92. * Invoking guix download:: Downloading a file and printing its hash.
  93. * Invoking guix hash:: Computing the cryptographic hash of a file.
  94. * Invoking guix import:: Importing package definitions.
  95. * Invoking guix refresh:: Updating package definitions.
  96. * Invoking guix lint:: Finding errors in package definitions.
  97. * Invoking guix environment:: Setting up development environments.
  98. GNU Distribution
  99. * System Installation:: Installing the whole operating system.
  100. * System Configuration:: Configuring a GNU system.
  101. * Installing Debugging Files:: Feeding the debugger.
  102. * Security Updates:: Deploying security fixes quickly.
  103. * Package Modules:: Packages from the programmer's viewpoint.
  104. * Packaging Guidelines:: Growing the distribution.
  105. * Bootstrapping:: GNU/Linux built from scratch.
  106. * Porting:: Targeting another platform or kernel.
  107. System Configuration
  108. * Using the Configuration System:: Customizing your GNU system.
  109. * operating-system Reference:: Detail of operating-system declarations.
  110. * File Systems:: Configuring file system mounts.
  111. * Mapped Devices:: Block device extra processing.
  112. * User Accounts:: Specifying user accounts.
  113. * Locales:: Language and cultural convention settings.
  114. * Services:: Specifying system services.
  115. * Setuid Programs:: Programs running with root privileges.
  116. * Initial RAM Disk:: Linux-Libre bootstrapping.
  117. * GRUB Configuration:: Configuring the boot loader.
  118. * Invoking guix system:: Instantiating a system configuration.
  119. * Defining Services:: Adding new service definitions.
  120. Services
  121. * Base Services:: Essential system services.
  122. * Networking Services:: Network setup, SSH daemon, etc.
  123. * X Window:: Graphical display.
  124. Packaging Guidelines
  125. * Software Freedom:: What may go into the distribution.
  126. * Package Naming:: What's in a name?
  127. * Version Numbers:: When the name is not enough.
  128. * Python Modules:: Taming the snake.
  129. * Perl Modules:: Little pearls.
  130. * Fonts:: Fond of fonts.
  131. @end detailmenu
  132. @end menu
  133. @c *********************************************************************
  134. @node Introduction
  135. @chapter Introduction
  136. GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
  137. using the international phonetic alphabet (IPA).} is a functional
  138. package management tool for the GNU system. Package management consists
  139. of all activities that relate to building packages from sources,
  140. honoring their build-time and run-time dependencies,
  141. installing packages in user environments, upgrading installed packages
  142. to new versions or rolling back to a previous set, removing unused
  143. software packages, etc.
  144. @cindex functional package management
  145. The term @dfn{functional} refers to a specific package management
  146. discipline. In Guix, the package build and installation process is seen
  147. as a function, in the mathematical sense. That function takes inputs,
  148. such as build scripts, a compiler, and libraries, and
  149. returns an installed package. As a pure function, its result depends
  150. solely on its inputs---for instance, it cannot refer to software or
  151. scripts that were not explicitly passed as inputs. A build function
  152. always produces the same result when passed a given set of inputs. It
  153. cannot alter the system's environment in
  154. any way; for instance, it cannot create, modify, or delete files outside
  155. of its build and installation directories. This is achieved by running
  156. build processes in isolated environments (or @dfn{containers}), where only their
  157. explicit inputs are visible.
  158. @cindex store
  159. The result of package build functions is @dfn{cached} in the file
  160. system, in a special directory called @dfn{the store} (@pxref{The
  161. Store}). Each package is installed in a directory of its own, in the
  162. store---by default under @file{/gnu/store}. The directory name contains
  163. a hash of all the inputs used to build that package; thus, changing an
  164. input yields a different directory name.
  165. This approach is the foundation of Guix's salient features: support for
  166. transactional package upgrade and rollback, per-user installation, and
  167. garbage collection of packages (@pxref{Features}).
  168. Guix has a command-line interface, which allows users to build, install,
  169. upgrade, and remove packages, as well as a Scheme programming interface.
  170. Last but not least, Guix is used to build a distribution of the GNU
  171. system, with many GNU and non-GNU free software packages. @xref{GNU
  172. Distribution}.
  173. @c *********************************************************************
  174. @node Installation
  175. @chapter Installation
  176. GNU Guix is available for download from its website at
  177. @url{}. This section describes the
  178. software requirements of Guix, as well as how to install it and get
  179. ready to use it.
  180. Note that this section is concerned with the installation of the package
  181. manager, which can be done on top of a running GNU/Linux system. If,
  182. instead, you want to install the complete GNU operating system,
  183. @pxref{System Installation}.
  184. The build procedure for Guix is the same as for other GNU software, and
  185. is not covered here. Please see the files @file{README} and
  186. @file{INSTALL} in the Guix source tree for additional details.
  187. @menu
  188. * Requirements:: Software needed to build and run Guix.
  189. * Setting Up the Daemon:: Preparing the build daemon's environment.
  190. * Invoking guix-daemon:: Running the build daemon.
  191. @end menu
  192. @node Requirements
  193. @section Requirements
  194. GNU Guix depends on the following packages:
  195. @itemize
  196. @item @url{, GNU Guile}, version 2.0.5 or later;
  197. @item @url{, GNU libgcrypt};
  198. @end itemize
  199. The following dependencies are optional:
  200. @itemize
  201. @item
  202. Installing
  203. @url{, Guile-JSON} will
  204. allow you to use the @command{guix import pypi} command (@pxref{Invoking
  205. guix import}). It is of
  206. interest primarily for developers and not for casual users.
  207. @item
  208. Installing @uref{, GnuTLS-Guile} will
  209. allow you to access @code{https} URLs with the @command{guix download}
  210. command (@pxref{Invoking guix download}) and the @command{guix import
  211. pypi} command. This is primarily of interest to developers.
  212. @xref{Guile Preparations, how to install the GnuTLS bindings for Guile,,
  213. gnutls-guile, GnuTLS-Guile}.
  214. @end itemize
  215. Unless @code{--disable-daemon} was passed to @command{configure}, the
  216. following packages are also needed:
  217. @itemize
  218. @item @url{, SQLite 3}
  219. @item @url{, libbz2}
  220. @item @url{, GCC's g++}
  221. @end itemize
  222. When a working installation of @url{, the Nix package
  223. manager} is available, you
  224. can instead configure Guix with @code{--disable-daemon}. In that case,
  225. Nix replaces the three dependencies above.
  226. Guix is compatible with Nix, so it is possible to share the same store
  227. between both. To do so, you must pass @command{configure} not only the
  228. same @code{--with-store-dir} value, but also the same
  229. @code{--localstatedir} value. The latter is essential because it
  230. specifies where the database that stores metadata about the store is
  231. located, among other things. The default values for Nix are
  232. @code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
  233. Note that @code{--disable-daemon} is not required if
  234. your goal is to share the store with Nix.
  235. @node Setting Up the Daemon
  236. @section Setting Up the Daemon
  237. @cindex daemon
  238. Operations such as building a package or running the garbage collector
  239. are all performed by a specialized process, the @dfn{build daemon}, on
  240. behalf of clients. Only the daemon may access the store and its
  241. associated database. Thus, any operation that manipulates the store
  242. goes through the daemon. For instance, command-line tools such as
  243. @command{guix package} and @command{guix build} communicate with the
  244. daemon (@i{via} remote procedure calls) to instruct it what to do.
  245. The following sections explain how to prepare the build daemon's
  246. environment.
  247. @menu
  248. * Build Environment Setup:: Preparing the isolated build environment.
  249. * Daemon Offload Setup:: Offloading builds to remote machines.
  250. @end menu
  251. @node Build Environment Setup
  252. @subsection Build Environment Setup
  253. In a standard multi-user setup, Guix and its daemon---the
  254. @command{guix-daemon} program---are installed by the system
  255. administrator; @file{/gnu/store} is owned by @code{root} and
  256. @command{guix-daemon} runs as @code{root}. Unprivileged users may use
  257. Guix tools to build packages or otherwise access the store, and the
  258. daemon will do it on their behalf, ensuring that the store is kept in a
  259. consistent state, and allowing built packages to be shared among users.
  260. @cindex build users
  261. When @command{guix-daemon} runs as @code{root}, you may not want package
  262. build processes themselves to run as @code{root} too, for obvious
  263. security reasons. To avoid that, a special pool of @dfn{build users}
  264. should be created for use by build processes started by the daemon.
  265. These build users need not have a shell and a home directory: they will
  266. just be used when the daemon drops @code{root} privileges in build
  267. processes. Having several such users allows the daemon to launch
  268. distinct build processes under separate UIDs, which guarantees that they
  269. do not interfere with each other---an essential feature since builds are
  270. regarded as pure functions (@pxref{Introduction}).
  271. On a GNU/Linux system, a build user pool may be created like this (using
  272. Bash syntax and the @code{shadow} commands):
  273. @c See
  274. @c for why `-G' is needed.
  275. @example
  276. # groupadd guix-builder
  277. # for i in `seq 1 10`;
  278. do
  279. useradd -g guix-builder -G guix-builder \
  280. -d /var/empty -s `which nologin` \
  281. -c "Guix build user $i" --system \
  282. guix-builder$i;
  283. done
  284. @end example
  285. The @file{/gnu/store} directory (or whichever was specified with the
  286. @code{--with-store-dir} option) must have ownership and permissions as
  287. follows:
  288. @example
  289. # chgrp guix-builder /gnu/store
  290. # chmod 1775 /gnu/store
  291. @end example
  292. @noindent
  293. The @code{guix-daemon} program may then be run as @code{root} with:
  294. @example
  295. # guix-daemon --build-users-group=guix-builder
  296. @end example
  297. @cindex chroot
  298. @noindent
  299. This way, the daemon starts build processes in a chroot, under one of
  300. the @code{guix-builder} users. On GNU/Linux, by default, the chroot
  301. environment contains nothing but:
  302. @c Keep this list in sync with libstore/! -----------------------
  303. @itemize
  304. @item
  305. a minimal @code{/dev} directory, created mostly independently from the
  306. host @code{/dev}@footnote{``Mostly'', because while the set of files
  307. that appear in the chroot's @code{/dev} is fixed, most of these files
  308. can only be created if the host has them.};
  309. @item
  310. the @code{/proc} directory; it only shows the container's processes
  311. since a separate PID name space is used;
  312. @item
  313. @file{/etc/passwd} with an entry for the current user and an entry for
  314. user @file{nobody};
  315. @item
  316. @file{/etc/group} with an entry for the user's group;
  317. @item
  318. @file{/etc/hosts} with an entry that maps @code{localhost} to
  319. @code{};
  320. @item
  321. a writable @file{/tmp} directory.
  322. @end itemize
  323. If you are installing Guix as an unprivileged user, it is still
  324. possible to run @command{guix-daemon}. However, build processes will
  325. not be isolated from one another, and not from the rest of the system.
  326. Thus, build processes may interfere with each other, and may access
  327. programs, libraries, and other files available on the system---making it
  328. much harder to view them as @emph{pure} functions.
  329. @node Daemon Offload Setup
  330. @subsection Using the Offload Facility
  331. @cindex offloading
  332. @cindex build hook
  333. When desired, the build daemon can @dfn{offload}
  334. derivation builds to other machines
  335. running Guix, using the @code{offload} @dfn{build hook}. When that
  336. feature is enabled, a list of user-specified build machines is read from
  337. @file{/etc/guix/machines.scm}; anytime a build is requested, for
  338. instance via @code{guix build}, the daemon attempts to offload it to one
  339. of the machines that satisfies the derivation's constraints, in
  340. particular its system type---e.g., @file{x86_64-linux}. Missing
  341. prerequisites for the build are copied over SSH to the target machine,
  342. which then proceeds with the build; upon success the output(s) of the
  343. build are copied back to the initial machine.
  344. The @file{/etc/guix/machines.scm} file typically looks like this:
  345. @example
  346. (list (build-machine
  347. (name "")
  348. (system "x86_64-linux")
  349. (user "bob")
  350. (speed 2.)) ; incredibly fast!
  351. (build-machine
  352. (name "")
  353. (system "mips64el-linux")
  354. (user "alice")
  355. (private-key
  356. (string-append (getenv "HOME")
  357. "/.ssh/id-rsa-for-guix"))))
  358. @end example
  359. @noindent
  360. In the example above we specify a list of two build machines, one for
  361. the @code{x86_64} architecture and one for the @code{mips64el}
  362. architecture.
  363. In fact, this file is---not surprisingly!---a Scheme file that is
  364. evaluated when the @code{offload} hook is started. Its return value
  365. must be a list of @code{build-machine} objects. While this example
  366. shows a fixed list of build machines, one could imagine, say, using
  367. DNS-SD to return a list of potential build machines discovered in the
  368. local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
  369. Avahi in Guile Scheme Programs}). The @code{build-machine} data type is
  370. detailed below.
  371. @deftp {Data Type} build-machine
  372. This data type represents build machines the daemon may offload builds
  373. to. The important fields are:
  374. @table @code
  375. @item name
  376. The remote machine's host name.
  377. @item system
  378. The remote machine's system type---e.g., @code{"x86_64-linux"}.
  379. @item user
  380. The user account to use when connecting to the remote machine over SSH.
  381. Note that the SSH key pair must @emph{not} be passphrase-protected, to
  382. allow non-interactive logins.
  383. @end table
  384. A number of optional fields may be specified:
  385. @table @code
  386. @item port
  387. Port number of the machine's SSH server (default: 22).
  388. @item private-key
  389. The SSH private key file to use when connecting to the machine.
  390. @item parallel-builds
  391. The number of builds that may run in parallel on the machine (1 by
  392. default.)
  393. @item speed
  394. A ``relative speed factor''. The offload scheduler will tend to prefer
  395. machines with a higher speed factor.
  396. @item features
  397. A list of strings denoting specific features supported by the machine.
  398. An example is @code{"kvm"} for machines that have the KVM Linux modules
  399. and corresponding hardware support. Derivations can request features by
  400. name, and they will be scheduled on matching build machines.
  401. @end table
  402. @end deftp
  403. The @code{guix} command must be in the search path on the build
  404. machines, since offloading works by invoking the @code{guix archive} and
  405. @code{guix build} commands.
  406. There's one last thing to do once @file{machines.scm} is in place. As
  407. explained above, when offloading, files are transferred back and forth
  408. between the machine stores. For this to work, you need to generate a
  409. key pair to allow the daemon to export signed archives of files from the
  410. store (@pxref{Invoking guix archive}):
  411. @example
  412. # guix archive --generate-key
  413. @end example
  414. @noindent
  415. Thus, when receiving files, a machine's build daemon can make sure they
  416. are genuine, have not been tampered with, and that they are signed by an
  417. authorized key.
  418. @node Invoking guix-daemon
  419. @section Invoking @command{guix-daemon}
  420. The @command{guix-daemon} program implements all the functionality to
  421. access the store. This includes launching build processes, running the
  422. garbage collector, querying the availability of a build result, etc. It
  423. is normally run as @code{root} like this:
  424. @example
  425. # guix-daemon --build-users-group=guix-builder
  426. @end example
  427. @noindent
  428. For details on how to set it up, @pxref{Setting Up the Daemon}.
  429. @cindex chroot
  430. @cindex container, build environment
  431. @cindex build environment
  432. @cindex reproducible builds
  433. By default, @command{guix-daemon} launches build processes under
  434. different UIDs, taken from the build group specified with
  435. @code{--build-users-group}. In addition, each build process is run in a
  436. chroot environment that only contains the subset of the store that the
  437. build process depends on, as specified by its derivation
  438. (@pxref{Programming Interface, derivation}), plus a set of specific
  439. system directories. By default, the latter contains @file{/dev} and
  440. @file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
  441. @dfn{container}: in addition to having its own file system tree, it has
  442. a separate mount name space, its own PID name space, network name space,
  443. etc. This helps achieve reproducible builds (@pxref{Features}).
  444. The following command-line options are supported:
  445. @table @code
  446. @item --build-users-group=@var{group}
  447. Take users from @var{group} to run build processes (@pxref{Setting Up
  448. the Daemon, build users}).
  449. @item --no-substitutes
  450. @cindex substitutes
  451. Do not use substitutes for build products. That is, always build things
  452. locally instead of allowing downloads of pre-built binaries
  453. (@pxref{Substitutes}).
  454. By default substitutes are used, unless the client---such as the
  455. @command{guix package} command---is explicitly invoked with
  456. @code{--no-substitutes}.
  457. When the daemon runs with @code{--no-substitutes}, clients can still
  458. explicitly enable substitution @i{via} the @code{set-build-options}
  459. remote procedure call (@pxref{The Store}).
  460. @item --substitute-urls=@var{urls}
  461. Consider @var{urls} the default whitespace-separated list of substitute
  462. source URLs. When this option is omitted, @code{}
  463. is used.
  464. This means that substitutes may be downloaded from @var{urls}, as long
  465. as they are signed by a trusted signature (@pxref{Substitutes}).
  466. @cindex build hook
  467. @item --no-build-hook
  468. Do not use the @dfn{build hook}.
  469. The build hook is a helper program that the daemon can start and to
  470. which it submits build requests. This mechanism is used to offload
  471. builds to other machines (@pxref{Daemon Offload Setup}).
  472. @item --cache-failures
  473. Cache build failures. By default, only successful builds are cached.
  474. @item --cores=@var{n}
  475. @itemx -c @var{n}
  476. Use @var{n} CPU cores to build each derivation; @code{0} means as many
  477. as available.
  478. The default value is @code{0}, but it may be overridden by clients, such
  479. as the @code{--cores} option of @command{guix build} (@pxref{Invoking
  480. guix build}).
  481. The effect is to define the @code{NIX_BUILD_CORES} environment variable
  482. in the build process, which can then use it to exploit internal
  483. parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
  484. @item --max-jobs=@var{n}
  485. @itemx -M @var{n}
  486. Allow at most @var{n} build jobs in parallel. The default value is
  487. @code{1}. Setting it to @code{0} means that no builds will be performed
  488. locally; instead, the daemon will offload builds (@pxref{Daemon Offload
  489. Setup}), or simply fail.
  490. @item --debug
  491. Produce debugging output.
  492. This is useful to debug daemon start-up issues, but then it may be
  493. overridden by clients, for example the @code{--verbosity} option of
  494. @command{guix build} (@pxref{Invoking guix build}).
  495. @item --chroot-directory=@var{dir}
  496. Add @var{dir} to the build chroot.
  497. Doing this may change the result of build processes---for instance if
  498. they use optional dependencies found in @var{dir} when it is available,
  499. and not otherwise. For that reason, it is not recommended to do so.
  500. Instead, make sure that each derivation declares all the inputs that it
  501. needs.
  502. @item --disable-chroot
  503. Disable chroot builds.
  504. Using this option is not recommended since, again, it would allow build
  505. processes to gain access to undeclared dependencies.
  506. @item --disable-log-compression
  507. Disable compression of the build logs.
  508. Unless @code{--lose-logs} is used, all the build logs are kept in the
  509. @var{localstatedir}. To save space, the daemon automatically compresses
  510. them with bzip2 by default. This option disables that.
  511. @item --disable-deduplication
  512. @cindex deduplication
  513. Disable automatic file ``deduplication'' in the store.
  514. By default, files added to the store are automatically ``deduplicated'':
  515. if a newly added file is identical to another one found in the store,
  516. the daemon makes the new file a hard link to the other file. This can
  517. noticeably reduce disk usage, at the expense of slightly increasde
  518. input/output load at the end of a build process. This option disables
  519. this optimization.
  520. @item --gc-keep-outputs[=yes|no]
  521. Tell whether the garbage collector (GC) must keep outputs of live
  522. derivations.
  523. When set to ``yes'', the GC will keep the outputs of any live derivation
  524. available in the store---the @code{.drv} files. The default is ``no'',
  525. meaning that derivation outputs are kept only if they are GC roots.
  526. @item --gc-keep-derivations[=yes|no]
  527. Tell whether the garbage collector (GC) must keep derivations
  528. corresponding to live outputs.
  529. When set to ``yes'', as is the case by default, the GC keeps
  530. derivations---i.e., @code{.drv} files---as long as at least one of their
  531. outputs is live. This allows users to keep track of the origins of
  532. items in their store. Setting it to ``no'' saves a bit of disk space.
  533. Note that when both @code{--gc-keep-derivations} and
  534. @code{--gc-keep-outputs} are used, the effect is to keep all the build
  535. prerequisites (the sources, compiler, libraries, and other build-time
  536. tools) of live objects in the store, regardless of whether these
  537. prerequisites are live. This is convenient for developers since it
  538. saves rebuilds or downloads.
  539. @item --impersonate-linux-2.6
  540. On Linux-based systems, impersonate Linux 2.6. This means that the
  541. kernel's @code{uname} system call will report 2.6 as the release number.
  542. This might be helpful to build programs that (usually wrongfully) depend
  543. on the kernel version number.
  544. @item --lose-logs
  545. Do not keep build logs. By default they are kept under
  546. @code{@var{localstatedir}/guix/log}.
  547. @item --system=@var{system}
  548. Assume @var{system} as the current system type. By default it is the
  549. architecture/kernel pair found at configure time, such as
  550. @code{x86_64-linux}.
  551. @item --listen=@var{socket}
  552. Listen for connections on @var{socket}, the file name of a Unix-domain
  553. socket. The default socket is
  554. @file{@var{localstatedir}/daemon-socket/socket}. This option is only
  555. useful in exceptional circumstances, such as if you need to run several
  556. daemons on the same machine.
  557. @end table
  558. @c *********************************************************************
  559. @node Package Management
  560. @chapter Package Management
  561. The purpose of GNU Guix is to allow users to easily install, upgrade, and
  562. remove software packages, without having to know about their build
  563. procedure or dependencies. Guix also goes beyond this obvious set of
  564. features.
  565. This chapter describes the main features of Guix, as well as the package
  566. management tools it provides. Two user interfaces are provided for
  567. routine package management tasks: a command-line interface
  568. (@pxref{Invoking guix package, @code{guix package}}), and a visual user
  569. interface in Emacs (@pxref{Emacs Interface}).
  570. @menu
  571. * Features:: How Guix will make your life brighter.
  572. * Invoking guix package:: Package installation, removal, etc.
  573. * Emacs Interface:: Package management from Emacs.
  574. * Substitutes:: Downloading pre-built binaries.
  575. * Packages with Multiple Outputs:: Single source package, multiple outputs.
  576. * Invoking guix gc:: Running the garbage collector.
  577. * Invoking guix pull:: Fetching the latest Guix and distribution.
  578. * Invoking guix archive:: Exporting and importing store files.
  579. @end menu
  580. @node Features
  581. @section Features
  582. When using Guix, each package ends up in the @dfn{package store}, in its
  583. own directory---something that resembles
  584. @file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string
  585. (note that Guix comes with an Emacs extension to shorten those file
  586. names, @pxref{Emacs Prettify}.)
  587. Instead of referring to these directories, users have their own
  588. @dfn{profile}, which points to the packages that they actually want to
  589. use. These profiles are stored within each user's home directory, at
  590. @code{$HOME/.guix-profile}.
  591. For example, @code{alice} installs GCC 4.7.2. As a result,
  592. @file{/home/alice/.guix-profile/bin/gcc} points to
  593. @file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
  594. @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
  595. simply continues to point to
  596. @file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
  597. coexist on the same system without any interference.
  598. The @command{guix package} command is the central tool to manage
  599. packages (@pxref{Invoking guix package}). It operates on those per-user
  600. profiles, and can be used @emph{with normal user privileges}.
  601. The command provides the obvious install, remove, and upgrade
  602. operations. Each invocation is actually a @emph{transaction}: either
  603. the specified operation succeeds, or nothing happens. Thus, if the
  604. @command{guix package} process is terminated during the transaction,
  605. or if a power outage occurs during the transaction, then the user's
  606. profile remains in its previous state, and remains usable.
  607. In addition, any package transaction may be @emph{rolled back}. So, if,
  608. for example, an upgrade installs a new version of a package that turns
  609. out to have a serious bug, users may roll back to the previous instance
  610. of their profile, which was known to work well. Similarly, the global
  611. system configuration is subject to transactional upgrades and roll-back
  612. (@pxref{Using the Configuration System}).
  613. All those packages in the package store may be @emph{garbage-collected}.
  614. Guix can determine which packages are still referenced by the user
  615. profiles, and remove those that are provably no longer referenced
  616. (@pxref{Invoking guix gc}). Users may also explicitly remove old
  617. generations of their profile so that the packages they refer to can be
  618. collected.
  619. @cindex reproducibility
  620. @cindex reproducible builds
  621. Finally, Guix takes a @dfn{purely functional} approach to package
  622. management, as described in the introduction (@pxref{Introduction}).
  623. Each @file{/gnu/store} package directory name contains a hash of all the
  624. inputs that were used to build that package---compiler, libraries, build
  625. scripts, etc. This direct correspondence allows users to make sure a
  626. given package installation matches the current state of their
  627. distribution. It also helps maximize @dfn{build reproducibility}:
  628. thanks to the isolated build environments that are used, a given build
  629. is likely to yield bit-identical files when performed on different
  630. machines (@pxref{Invoking guix-daemon, container}).
  631. @cindex substitutes
  632. This foundation allows Guix to support @dfn{transparent binary/source
  633. deployment}. When a pre-built binary for a @file{/gnu/store} item is
  634. available from an external source---a @dfn{substitute}, Guix just
  635. downloads it and unpacks it;
  636. otherwise, it builds the package from source, locally
  637. (@pxref{Substitutes}).
  638. Control over the build environment is a feature that is also useful for
  639. developers. The @command{guix environment} command allows developers of
  640. a package to quickly set up the right development environment for their
  641. package, without having to manually install the package's dependencies
  642. in their profile (@pxref{Invoking guix environment}).
  643. @node Invoking guix package
  644. @section Invoking @command{guix package}
  645. The @command{guix package} command is the tool that allows users to
  646. install, upgrade, and remove packages, as well as rolling back to
  647. previous configurations. It operates only on the user's own profile,
  648. and works with normal user privileges (@pxref{Features}). Its syntax
  649. is:
  650. @example
  651. guix package @var{options}
  652. @end example
  653. Primarily, @var{options} specifies the operations to be performed during
  654. the transaction. Upon completion, a new profile is created, but
  655. previous generations of the profile remain available, should the user
  656. want to roll back.
  657. For example, to remove @code{lua} and install @code{guile} and
  658. @code{guile-cairo} in a single transaction:
  659. @example
  660. guix package -r lua -i guile guile-cairo
  661. @end example
  662. For each user, a symlink to the user's default profile is automatically
  663. created in @file{$HOME/.guix-profile}. This symlink always points to the
  664. current generation of the user's default profile. Thus, users can add
  665. @file{$HOME/.guix-profile/bin} to their @code{PATH} environment
  666. variable, and so on.
  667. In a multi-user setup, user profiles are stored in a place registered as
  668. a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
  669. to (@pxref{Invoking guix gc}). That directory is normally
  670. @code{@var{localstatedir}/profiles/per-user/@var{user}}, where
  671. @var{localstatedir} is the value passed to @code{configure} as
  672. @code{--localstatedir}, and @var{user} is the user name. The
  673. @file{per-user} directory is created when @command{guix-daemon} is
  674. started, and the @var{user} sub-directory is created by @command{guix
  675. package}.
  676. The @var{options} can be among the following:
  677. @table @code
  678. @item --install=@var{package} @dots{}
  679. @itemx -i @var{package} @dots{}
  680. Install the specified @var{package}s.
  681. Each @var{package} may specify either a simple package name, such as
  682. @code{guile}, or a package name followed by a hyphen and version number,
  683. such as @code{guile-1.8.8}. If no version number is specified, the
  684. newest available version will be selected. In addition, @var{package}
  685. may contain a colon, followed by the name of one of the outputs of the
  686. package, as in @code{gcc:doc} or @code{binutils-2.22:lib}
  687. (@pxref{Packages with Multiple Outputs}). Packages with a corresponding
  688. name (and optionally version) are searched for among the GNU
  689. distribution modules (@pxref{Package Modules}).
  690. @cindex propagated inputs
  691. Sometimes packages have @dfn{propagated inputs}: these are dependencies
  692. that automatically get installed along with the required package.
  693. An example is the GNU MPC library: its C header files refer to those of
  694. the GNU MPFR library, which in turn refer to those of the GMP library.
  695. Thus, when installing MPC, the MPFR and GMP libraries also get installed
  696. in the profile; removing MPC also removes MPFR and GMP---unless they had
  697. also been explicitly installed independently.
  698. Besides, packages sometimes rely on the definition of environment
  699. variables for their search paths (see explanation of
  700. @code{--search-paths} below). Any missing or possibly incorrect
  701. environment variable definitions are reported here.
  702. @c XXX: keep me up-to-date
  703. Finally, when installing a GNU package, the tool reports the
  704. availability of a newer upstream version. In the future, it may provide
  705. the option of installing directly from the upstream version, even if
  706. that version is not yet in the distribution.
  707. @item --install-from-expression=@var{exp}
  708. @itemx -e @var{exp}
  709. Install the package @var{exp} evaluates to.
  710. @var{exp} must be a Scheme expression that evaluates to a
  711. @code{<package>} object. This option is notably useful to disambiguate
  712. between same-named variants of a package, with expressions such as
  713. @code{(@@ (gnu packages base) guile-final)}.
  714. Note that this option installs the first output of the specified
  715. package, which may be insufficient when needing a specific output of a
  716. multiple-output package.
  717. @item --remove=@var{package} @dots{}
  718. @itemx -r @var{package} @dots{}
  719. Remove the specified @var{package}s.
  720. As for @code{--install}, each @var{package} may specify a version number
  721. and/or output name in addition to the package name. For instance,
  722. @code{-r glibc:debug} would remove the @code{debug} output of
  723. @code{glibc}.
  724. @item --upgrade[=@var{regexp} @dots{}]
  725. @itemx -u [@var{regexp} @dots{}]
  726. Upgrade all the installed packages. If one or more @var{regexp}s are
  727. specified, upgrade only installed packages whose name matches a
  728. @var{regexp}.
  729. Note that this upgrades package to the latest version of packages found
  730. in the distribution currently installed. To update your distribution,
  731. you should regularly run @command{guix pull} (@pxref{Invoking guix
  732. pull}).
  733. @item --roll-back
  734. Roll back to the previous @dfn{generation} of the profile---i.e., undo
  735. the last transaction.
  736. When combined with options such as @code{--install}, roll back occurs
  737. before any other actions.
  738. When rolling back from the first generation that actually contains
  739. installed packages, the profile is made to point to the @dfn{zeroth
  740. generation}, which contains no files apart from its own meta-data.
  741. Installing, removing, or upgrading packages from a generation that has
  742. been rolled back to overwrites previous future generations. Thus, the
  743. history of a profile's generations is always linear.
  744. @item --switch-generation=@var{pattern}
  745. @itemx -S @var{pattern}
  746. Switch to a particular generation defined by @var{pattern}.
  747. @var{pattern} may be either a generation number or a number prefixed
  748. with ``+'' or ``-''. The latter means: move forward/backward by a
  749. specified number of generations. For example, if you want to return to
  750. the latest generation after @code{--roll-back}, use
  751. @code{--switch-generation=+1}.
  752. The difference between @code{--roll-back} and
  753. @code{--switch-generation=-1} is that @code{--switch-generation} will
  754. not make a zeroth generation, so if a specified generation does not
  755. exist, the current generation will not be changed.
  756. @item --search-paths
  757. @cindex search paths
  758. Report environment variable definitions, in Bash syntax, that may be
  759. needed in order to use the set of installed packages. These environment
  760. variables are used to specify @dfn{search paths} for files used by some
  761. of the installed packages.
  762. For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
  763. environment variables to be defined so it can look for headers and
  764. libraries in the user's profile (@pxref{Environment Variables,,, gcc,
  765. Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
  766. library are installed in the profile, then @code{--search-paths} will
  767. suggest setting these variables to @code{@var{profile}/include} and
  768. @code{@var{profile}/lib}, respectively.
  769. @item --profile=@var{profile}
  770. @itemx -p @var{profile}
  771. Use @var{profile} instead of the user's default profile.
  772. @item --verbose
  773. Produce verbose output. In particular, emit the environment's build log
  774. on the standard error port.
  775. @item --bootstrap
  776. Use the bootstrap Guile to build the profile. This option is only
  777. useful to distribution developers.
  778. @end table
  779. In addition to these actions @command{guix package} supports the
  780. following options to query the current state of a profile, or the
  781. availability of packages:
  782. @table @option
  783. @item --search=@var{regexp}
  784. @itemx -s @var{regexp}
  785. List the available packages whose synopsis or description matches
  786. @var{regexp}. Print all the meta-data of matching packages in
  787. @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
  788. GNU recutils manual}).
  789. This allows specific fields to be extracted using the @command{recsel}
  790. command, for instance:
  791. @example
  792. $ guix package -s malloc | recsel -p name,version
  793. name: glibc
  794. version: 2.17
  795. name: libgc
  796. version: 7.2alpha6
  797. @end example
  798. Similarly, to show the name of all the packages available under the
  799. terms of the GNU@tie{}LGPL version 3:
  800. @example
  801. $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
  802. name: elfutils
  803. name: gmp
  804. @dots{}
  805. @end example
  806. @item --show=@var{package}
  807. Show details about @var{package}, taken from the list of available packages, in
  808. @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
  809. recutils manual}).
  810. @example
  811. $ guix package --show=python | recsel -p name,version
  812. name: python
  813. version: 2.7.6
  814. name: python
  815. version: 3.3.5
  816. @end example
  817. You may also specify the full name of a package to only get details about a
  818. specific version of it:
  819. @example
  820. $ guix package --show=python-3.3.5 | recsel -p name,version
  821. name: python
  822. version: 3.3.5
  823. @end example
  824. @item --list-installed[=@var{regexp}]
  825. @itemx -I [@var{regexp}]
  826. List the currently installed packages in the specified profile, with the
  827. most recently installed packages shown last. When @var{regexp} is
  828. specified, list only installed packages whose name matches @var{regexp}.
  829. For each installed package, print the following items, separated by
  830. tabs: the package name, its version string, the part of the package that
  831. is installed (for instance, @code{out} for the default output,
  832. @code{include} for its headers, etc.), and the path of this package in
  833. the store.
  834. @item --list-available[=@var{regexp}]
  835. @itemx -A [@var{regexp}]
  836. List packages currently available in the software distribution
  837. (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
  838. installed packages whose name matches @var{regexp}.
  839. For each package, print the following items separated by tabs: its name,
  840. its version string, the parts of the package (@pxref{Packages with
  841. Multiple Outputs}), and the source location of its definition.
  842. @item --list-generations[=@var{pattern}]
  843. @itemx -l [@var{pattern}]
  844. Return a list of generations along with their creation dates; for each
  845. generation, show the installed packages, with the most recently
  846. installed packages shown last. Note that the zeroth generation is never
  847. shown.
  848. For each installed package, print the following items, separated by
  849. tabs: the name of a package, its version string, the part of the package
  850. that is installed (@pxref{Packages with Multiple Outputs}), and the
  851. location of this package in the store.
  852. When @var{pattern} is used, the command returns only matching
  853. generations. Valid patterns include:
  854. @itemize
  855. @item @emph{Integers and comma-separated integers}. Both patterns denote
  856. generation numbers. For instance, @code{--list-generations=1} returns
  857. the first one.
  858. And @code{--list-generations=1,8,2} outputs three generations in the
  859. specified order. Neither spaces nor trailing commas are allowed.
  860. @item @emph{Ranges}. @code{--list-generations=2..9} prints the
  861. specified generations and everything in between. Note that the start of
  862. a range must be lesser than its end.
  863. It is also possible to omit the endpoint. For example,
  864. @code{--list-generations=2..}, returns all generations starting from the
  865. second one.
  866. @item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
  867. or months by passing an integer along with the first letter of the
  868. duration. For example, @code{--list-generations=20d} lists generations
  869. that are up to 20 days old.
  870. @end itemize
  871. @item --delete-generations[=@var{pattern}]
  872. @itemx -d [@var{pattern}]
  873. When @var{pattern} is omitted, delete all generations except the current
  874. one.
  875. This command accepts the same patterns as @option{--list-generations}.
  876. When @var{pattern} is specified, delete the matching generations. When
  877. @var{pattern} specifies a duration, generations @emph{older} than the
  878. specified duration match. For instance, @code{--delete-generations=1m}
  879. deletes generations that are more than one month old.
  880. If the current generation matches, it is deleted atomically---i.e., by
  881. switching to the previous available generation. Note that the zeroth
  882. generation is never deleted.
  883. Note that deleting generations prevents roll-back to them.
  884. Consequently, this command must be used with care.
  885. @end table
  886. Finally, since @command{guix package} may actually start build
  887. processes, it supports all the common build options that @command{guix
  888. build} supports (@pxref{Invoking guix build, common build options}).
  889. @include emacs.texi
  890. @node Substitutes
  891. @section Substitutes
  892. @cindex substitutes
  893. @cindex pre-built binaries
  894. Guix supports transparent source/binary deployment, which means that it
  895. can either build things locally, or download pre-built items from a
  896. server. We call these pre-built items @dfn{substitutes}---they are
  897. substitutes for local build results. In many cases, downloading a
  898. substitute is much faster than building things locally.
  899. Substitutes can be anything resulting from a derivation build
  900. (@pxref{Derivations}). Of course, in the common case, they are
  901. pre-built package binaries, but source tarballs, for instance, which
  902. also result from derivation builds, can be available as substitutes.
  903. The @code{} server is a front-end to a build farm that
  904. builds packages from the GNU distribution continuously for some
  905. architectures, and makes them available as substitutes. This is the
  906. default source of substitutes; it can be overridden by passing
  907. @command{guix-daemon} the @code{--substitute-urls} option
  908. (@pxref{Invoking guix-daemon}).
  909. @cindex security
  910. @cindex digital signatures
  911. To allow Guix to download substitutes from @code{}, you
  912. must add its public key to the access control list (ACL) of archive
  913. imports, using the @command{guix archive} command (@pxref{Invoking guix
  914. archive}). Doing so implies that you trust @code{} to not
  915. be compromised and to serve genuine substitutes.
  916. This public key is installed along with Guix, in
  917. @code{@var{prefix}/share/guix/}, where @var{prefix} is
  918. the installation prefix of Guix. If you installed Guix from source,
  919. make sure you checked the GPG signature of
  920. @file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
  921. Then, you can run something like this:
  922. @example
  923. # guix archive --authorize <
  924. @end example
  925. Once this is in place, the output of a command like @code{guix build}
  926. should change from something like:
  927. @example
  928. $ guix build emacs --dry-run
  929. The following derivations would be built:
  930. /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
  931. /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
  932. /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-
  933. /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
  934. @dots{}
  935. @end example
  936. @noindent
  937. to something like:
  938. @example
  939. $ guix build emacs --dry-run
  940. The following files would be downloaded:
  941. /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
  942. /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
  943. /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
  944. /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
  945. @dots{}
  946. @end example
  947. @noindent
  948. This indicates that substitutes from @code{} are usable and
  949. will be downloaded, when possible, for future builds.
  950. Guix ignores substitutes that are not signed, or that are not signed by
  951. one of the keys listed in the ACL. It also detects and raises an error
  952. when attempting to use a substitute that has been tampered with.
  953. The substitute mechanism can be disabled globally by running
  954. @code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
  955. guix-daemon}). It can also be disabled temporarily by passing the
  956. @code{--no-substitutes} option to @command{guix package}, @command{guix
  957. build}, and other command-line tools.
  958. Today, each individual's control over their own computing is at the
  959. mercy of institutions, corporations, and groups with enough power and
  960. determination to subvert the computing infrastructure and exploit its
  961. weaknesses. While using @code{} substitutes can be
  962. convenient, we encourage users to also build on their own, or even run
  963. their own build farm, such that @code{} is less of an
  964. interesting target.
  965. Guix has the foundations to maximize build reproducibility
  966. (@pxref{Features}). In most cases, independent builds of a given
  967. package or derivation should yield bit-identical results. Thus, through
  968. a diverse set of independent package builds, we can strengthen the
  969. integrity of our systems.
  970. In the future, we want Guix to have support to publish and retrieve
  971. binaries to/from other users, in a peer-to-peer fashion. If you would
  972. like to discuss this project, join us on @email{}.
  973. @node Packages with Multiple Outputs
  974. @section Packages with Multiple Outputs
  975. @cindex multiple-output packages
  976. @cindex package outputs
  977. Often, packages defined in Guix have a single @dfn{output}---i.e., the
  978. source package leads exactly one directory in the store. When running
  979. @command{guix package -i glibc}, one installs the default output of the
  980. GNU libc package; the default output is called @code{out}, but its name
  981. can be omitted as shown in this command. In this particular case, the
  982. default output of @code{glibc} contains all the C header files, shared
  983. libraries, static libraries, Info documentation, and other supporting
  984. files.
  985. Sometimes it is more appropriate to separate the various types of files
  986. produced from a single source package into separate outputs. For
  987. instance, the GLib C library (used by GTK+ and related packages)
  988. installs more than 20 MiB of reference documentation as HTML pages.
  989. To save space for users who do not need it, the documentation goes to a
  990. separate output, called @code{doc}. To install the main GLib output,
  991. which contains everything but the documentation, one would run:
  992. @example
  993. guix package -i glib
  994. @end example
  995. The command to install its documentation is:
  996. @example
  997. guix package -i glib:doc
  998. @end example
  999. Some packages install programs with different ``dependency footprints''.
  1000. For instance, the WordNet package install both command-line tools and
  1001. graphical user interfaces (GUIs). The former depend solely on the C
  1002. library, whereas the latter depend on Tcl/Tk and the underlying X
  1003. libraries. In this case, we leave the command-line tools in the default
  1004. output, whereas the GUIs are in a separate output. This allows users
  1005. who do not need the GUIs to save space.
  1006. There are several such multiple-output packages in the GNU distribution.
  1007. Other conventional output names include @code{lib} for libraries and
  1008. possibly header files, @code{bin} for stand-alone programs, and
  1009. @code{debug} for debugging information (@pxref{Installing Debugging
  1010. Files}). The outputs of a packages are listed in the third column of
  1011. the output of @command{guix package --list-available} (@pxref{Invoking
  1012. guix package}).
  1013. @node Invoking guix gc
  1014. @section Invoking @command{guix gc}
  1015. @cindex garbage collector
  1016. Packages that are installed but not used may be @dfn{garbage-collected}.
  1017. The @command{guix gc} command allows users to explicitly run the garbage
  1018. collector to reclaim space from the @file{/gnu/store} directory.
  1019. The garbage collector has a set of known @dfn{roots}: any file under
  1020. @file{/gnu/store} reachable from a root is considered @dfn{live} and
  1021. cannot be deleted; any other file is considered @dfn{dead} and may be
  1022. deleted. The set of garbage collector roots includes default user
  1023. profiles, and may be augmented with @command{guix build --root}, for
  1024. example (@pxref{Invoking guix build}).
  1025. Prior to running @code{guix gc --collect-garbage} to make space, it is
  1026. often useful to remove old generations from user profiles; that way, old
  1027. package builds referenced by those generations can be reclaimed. This
  1028. is achieved by running @code{guix package --delete-generations}
  1029. (@pxref{Invoking guix package}).
  1030. The @command{guix gc} command has three modes of operation: it can be
  1031. used to garbage-collect any dead files (the default), to delete specific
  1032. files (the @code{--delete} option), or to print garbage-collector
  1033. information. The available options are listed below:
  1034. @table @code
  1035. @item --collect-garbage[=@var{min}]
  1036. @itemx -C [@var{min}]
  1037. Collect garbage---i.e., unreachable @file{/gnu/store} files and
  1038. sub-directories. This is the default operation when no option is
  1039. specified.
  1040. When @var{min} is given, stop once @var{min} bytes have been collected.
  1041. @var{min} may be a number of bytes, or it may include a unit as a
  1042. suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
  1043. (@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
  1044. When @var{min} is omitted, collect all the garbage.
  1045. @item --delete
  1046. @itemx -d
  1047. Attempt to delete all the store files and directories specified as
  1048. arguments. This fails if some of the files are not in the store, or if
  1049. they are still live.
  1050. @item --list-dead
  1051. Show the list of dead files and directories still present in the
  1052. store---i.e., files and directories no longer reachable from any root.
  1053. @item --list-live
  1054. Show the list of live store files and directories.
  1055. @end table
  1056. In addition, the references among existing store files can be queried:
  1057. @table @code
  1058. @item --references
  1059. @itemx --referrers
  1060. List the references (respectively, the referrers) of store files given
  1061. as arguments.
  1062. @item --requisites
  1063. @itemx -R
  1064. List the requisites of the store files passed as arguments. Requisites
  1065. include the store files themselves, their references, and the references
  1066. of these, recursively. In other words, the returned list is the
  1067. @dfn{transitive closure} of the store files.
  1068. @end table
  1069. @node Invoking guix pull
  1070. @section Invoking @command{guix pull}
  1071. Packages are installed or upgraded to the latest version available in
  1072. the distribution currently available on your local machine. To update
  1073. that distribution, along with the Guix tools, you must run @command{guix
  1074. pull}: the command downloads the latest Guix source code and package
  1075. descriptions, and deploys it.
  1076. On completion, @command{guix package} will use packages and package
  1077. versions from this just-retrieved copy of Guix. Not only that, but all
  1078. the Guix commands and Scheme modules will also be taken from that latest
  1079. version. New @command{guix} sub-commands added by the update also
  1080. become available.
  1081. The @command{guix pull} command is usually invoked with no arguments,
  1082. but it supports the following options:
  1083. @table @code
  1084. @item --verbose
  1085. Produce verbose output, writing build logs to the standard error output.
  1086. @item --url=@var{url}
  1087. Download the source tarball of Guix from @var{url}.
  1088. By default, the tarball is taken from its canonical address at
  1089. @code{}, for the stable branch of Guix.
  1090. @item --bootstrap
  1091. Use the bootstrap Guile to build the latest Guix. This option is only
  1092. useful to Guix developers.
  1093. @end table
  1094. @node Invoking guix archive
  1095. @section Invoking @command{guix archive}
  1096. The @command{guix archive} command allows users to @dfn{export} files
  1097. from the store into a single archive, and to later @dfn{import} them.
  1098. In particular, it allows store files to be transferred from one machine
  1099. to another machine's store. For example, to transfer the @code{emacs}
  1100. package to a machine connected over SSH, one would run:
  1101. @example
  1102. guix archive --export emacs | ssh the-machine guix archive --import
  1103. @end example
  1104. @noindent
  1105. However, note that, in this example, all of @code{emacs} and its
  1106. dependencies are transferred, regardless of what is already available in
  1107. the target machine's store. The @code{--missing} option can help figure
  1108. out which items are missing from the target's store.
  1109. Archives are stored in the ``Nix archive'' or ``Nar'' format, which is
  1110. comparable in spirit to `tar', but with a few noteworthy differences
  1111. that make it more appropriate for our purposes. First, rather than
  1112. recording all Unix meta-data for each file, the Nar format only mentions
  1113. the file type (regular, directory, or symbolic link); Unix permissions
  1114. and owner/group are dismissed. Second, the order in which directory
  1115. entries are stored always follows the order of file names according to
  1116. the C locale collation order. This makes archive production fully
  1117. deterministic.
  1118. When exporting, the daemon digitally signs the contents of the archive,
  1119. and that digital signature is appended. When importing, the daemon
  1120. verifies the signature and rejects the import in case of an invalid
  1121. signature or if the signing key is not authorized.
  1122. @c FIXME: Add xref to daemon doc about signatures.
  1123. The main options are:
  1124. @table @code
  1125. @item --export
  1126. Export the specified store files or packages (see below.) Write the
  1127. resulting archive to the standard output.
  1128. @item --import
  1129. Read an archive from the standard input, and import the files listed
  1130. therein into the store. Abort if the archive has an invalid digital
  1131. signature, or if it is signed by a public key not among the authorized
  1132. keys (see @code{--authorize} below.)
  1133. @item --missing
  1134. Read a list of store file names from the standard input, one per line,
  1135. and write on the standard output the subset of these files missing from
  1136. the store.
  1137. @item --generate-key[=@var{parameters}]
  1138. @cindex signing, archives
  1139. Generate a new key pair for the daemons. This is a prerequisite before
  1140. archives can be exported with @code{--export}. Note that this operation
  1141. usually takes time, because it needs to gather enough entropy to
  1142. generate the key pair.
  1143. The generated key pair is typically stored under @file{/etc/guix}, in
  1144. @file{} (public key) and @file{signing-key.sec} (private
  1145. key, which must be kept secret.) When @var{parameters} is omitted, it
  1146. is a 4096-bit RSA key. Alternately, @var{parameters} can specify
  1147. @code{genkey} parameters suitable for Libgcrypt (@pxref{General
  1148. public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
  1149. Libgcrypt Reference Manual}).
  1150. @item --authorize
  1151. @cindex authorizing, archives
  1152. Authorize imports signed by the public key passed on standard input.
  1153. The public key must be in ``s-expression advanced format''---i.e., the
  1154. same format as the @file{} file.
  1155. The list of authorized keys is kept in the human-editable file
  1156. @file{/etc/guix/acl}. The file contains
  1157. @url{, ``advanced-format
  1158. s-expressions''} and is structured as an access-control list in the
  1159. @url{, Simple Public-Key Infrastructure
  1160. (SPKI)}.
  1161. @end table
  1162. To export store files as an archive to the standard output, run:
  1163. @example
  1164. guix archive --export @var{options} @var{specifications}...
  1165. @end example
  1166. @var{specifications} may be either store file names or package
  1167. specifications, as for @command{guix package} (@pxref{Invoking guix
  1168. package}). For instance, the following command creates an archive
  1169. containing the @code{gui} output of the @code{git} package and the main
  1170. output of @code{emacs}:
  1171. @example
  1172. guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
  1173. @end example
  1174. If the specified packages are not built yet, @command{guix archive}
  1175. automatically builds them. The build process may be controlled with the
  1176. same options that can be passed to the @command{guix build} command
  1177. (@pxref{Invoking guix build, common build options}).
  1178. @c *********************************************************************
  1179. @node Programming Interface
  1180. @chapter Programming Interface
  1181. GNU Guix provides several Scheme programming interfaces (APIs) to
  1182. define, build, and query packages. The first interface allows users to
  1183. write high-level package definitions. These definitions refer to
  1184. familiar packaging concepts, such as the name and version of a package,
  1185. its build system, and its dependencies. These definitions can then be
  1186. turned into concrete build actions.
  1187. Build actions are performed by the Guix daemon, on behalf of users. In a
  1188. standard setup, the daemon has write access to the store---the
  1189. @file{/gnu/store} directory---whereas users do not. The recommended
  1190. setup also has the daemon perform builds in chroots, under a specific
  1191. build users, to minimize interference with the rest of the system.
  1192. @cindex derivation
  1193. Lower-level APIs are available to interact with the daemon and the
  1194. store. To instruct the daemon to perform a build action, users actually
  1195. provide it with a @dfn{derivation}. A derivation is a low-level
  1196. representation of the build actions to be taken, and the environment in
  1197. which they should occur---derivations are to package definitions what
  1198. assembly is to C programs. The term ``derivation'' comes from the fact
  1199. that build results @emph{derive} from them.
  1200. This chapter describes all these APIs in turn, starting from high-level
  1201. package definitions.
  1202. @menu
  1203. * Defining Packages:: Defining new packages.
  1204. * Build Systems:: Specifying how packages are built.
  1205. * The Store:: Manipulating the package store.
  1206. * Derivations:: Low-level interface to package derivations.
  1207. * The Store Monad:: Purely functional interface to the store.
  1208. * G-Expressions:: Manipulating build expressions.
  1209. @end menu
  1210. @node Defining Packages
  1211. @section Defining Packages
  1212. The high-level interface to package definitions is implemented in the
  1213. @code{(guix packages)} and @code{(guix build-system)} modules. As an
  1214. example, the package definition, or @dfn{recipe}, for the GNU Hello
  1215. package looks like this:
  1216. @example
  1217. (define-module (gnu packages hello)
  1218. #:use-module (guix packages)
  1219. #:use-module (guix download)
  1220. #:use-module (guix build-system gnu)
  1221. #:use-module (guix licenses))
  1222. (define-public hello
  1223. (package
  1224. (name "hello")
  1225. (version "2.8")
  1226. (source (origin
  1227. (method url-fetch)
  1228. (uri (string-append "mirror://gnu/hello/hello-" version
  1229. ".tar.gz"))
  1230. (sha256
  1231. (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
  1232. (build-system gnu-build-system)
  1233. (arguments `(#:configure-flags '("--enable-silent-rules")))
  1234. (inputs `(("gawk" ,gawk)))
  1235. (synopsis "Hello, GNU world: An example GNU package")
  1236. (description "Guess what GNU Hello prints!")
  1237. (home-page "")
  1238. (license gpl3+)))
  1239. @end example
  1240. @noindent
  1241. Without being a Scheme expert, the reader may have guessed the meaning
  1242. of the various fields here. This expression binds variable @code{hello}
  1243. to a @code{<package>} object, which is essentially a record
  1244. (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
  1245. This package object can be inspected using procedures found in the
  1246. @code{(guix packages)} module; for instance, @code{(package-name hello)}
  1247. returns---surprise!---@code{"hello"}.
  1248. With luck, you may be able to import part or all of the definition of
  1249. the package you are interested in from another repository, using the
  1250. @code{guix import} command (@pxref{Invoking guix import}).
  1251. In the example above, @var{hello} is defined into a module of its own,
  1252. @code{(gnu packages hello)}. Technically, this is not strictly
  1253. necessary, but it is convenient to do so: all the packages defined in
  1254. modules under @code{(gnu packages @dots{})} are automatically known to
  1255. the command-line tools (@pxref{Package Modules}).
  1256. There are a few points worth noting in the above package definition:
  1257. @itemize
  1258. @item
  1259. The @code{source} field of the package is an @code{<origin>} object.
  1260. Here, the @code{url-fetch} method from @code{(guix download)} is used,
  1261. meaning that the source is a file to be downloaded over FTP or HTTP.
  1262. The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
  1263. the GNU mirrors defined in @code{(guix download)}.
  1264. The @code{sha256} field specifies the expected SHA256 hash of the file
  1265. being downloaded. It is mandatory, and allows Guix to check the
  1266. integrity of the file. The @code{(base32 @dots{})} form introduces the
  1267. base32 representation of the hash. You can obtain this information with
  1268. @code{guix download} (@pxref{Invoking guix download}) and @code{guix
  1269. hash} (@pxref{Invoking guix hash}).
  1270. @cindex patches
  1271. When needed, the @code{origin} form can also have a @code{patches} field
  1272. listing patches to be applied, and a @code{snippet} field giving a
  1273. Scheme expression to modify the source code.
  1274. @item
  1275. @cindex GNU Build System
  1276. The @code{build-system} field specifies the procedure to build the
  1277. package (@pxref{Build Systems}). Here, @var{gnu-build-system}
  1278. represents the familiar GNU Build System, where packages may be
  1279. configured, built, and installed with the usual @code{./configure &&
  1280. make && make check && make install} command sequence.
  1281. @item
  1282. The @code{arguments} field specifies options for the build system
  1283. (@pxref{Build Systems}). Here it is interpreted by
  1284. @var{gnu-build-system} as a request run @file{configure} with the
  1285. @code{--enable-silent-rules} flag.
  1286. @item
  1287. The @code{inputs} field specifies inputs to the build process---i.e.,
  1288. build-time or run-time dependencies of the package. Here, we define an
  1289. input called @code{"gawk"} whose value is that of the @var{gawk}
  1290. variable; @var{gawk} is itself bound to a @code{<package>} object.
  1291. Note that GCC, Coreutils, Bash, and other essential tools do not need to
  1292. be specified as inputs here. Instead, @var{gnu-build-system} takes care
  1293. of ensuring that they are present (@pxref{Build Systems}).
  1294. However, any other dependencies need to be specified in the
  1295. @code{inputs} field. Any dependency not specified here will simply be
  1296. unavailable to the build process, possibly leading to a build failure.
  1297. @end itemize
  1298. Once a package definition is in place, the
  1299. package may actually be built using the @code{guix build} command-line
  1300. tool (@pxref{Invoking guix build}). @xref{Packaging Guidelines}, for
  1301. more information on how to test package definitions, and
  1302. @ref{Invoking guix lint}, for information on how to check a definition
  1303. for style conformance.
  1304. Eventually, updating the package definition to a new upstream version
  1305. can be partly automated by the @command{guix refresh} command
  1306. (@pxref{Invoking guix refresh}).
  1307. Behind the scenes, a derivation corresponding to the @code{<package>}
  1308. object is first computed by the @code{package-derivation} procedure.
  1309. That derivation is stored in a @code{.drv} file under @file{/gnu/store}.
  1310. The build actions it prescribes may then be realized by using the
  1311. @code{build-derivations} procedure (@pxref{The Store}).
  1312. @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
  1313. Return the @code{<derivation>} object of @var{package} for @var{system}
  1314. (@pxref{Derivations}).
  1315. @var{package} must be a valid @code{<package>} object, and @var{system}
  1316. must be a string denoting the target system type---e.g.,
  1317. @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
  1318. must be a connection to the daemon, which operates on the store
  1319. (@pxref{The Store}).
  1320. @end deffn
  1321. @noindent
  1322. @cindex cross-compilation
  1323. Similarly, it is possible to compute a derivation that cross-builds a
  1324. package for some other system:
  1325. @deffn {Scheme Procedure} package-cross-derivation @var{store} @
  1326. @var{package} @var{target} [@var{system}]
  1327. Return the @code{<derivation>} object of @var{package} cross-built from
  1328. @var{system} to @var{target}.
  1329. @var{target} must be a valid GNU triplet denoting the target hardware
  1330. and operating system, such as @code{"mips64el-linux-gnu"}
  1331. (@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
  1332. Configure and Build System}).
  1333. @end deffn
  1334. @node Build Systems
  1335. @section Build Systems
  1336. @cindex build system
  1337. Each package definition specifies a @dfn{build system} and arguments for
  1338. that build system (@pxref{Defining Packages}). This @code{build-system}
  1339. field represents the build procedure of the package, as well implicit
  1340. dependencies of that build procedure.
  1341. Build systems are @code{<build-system>} objects. The interface to
  1342. create and manipulate them is provided by the @code{(guix build-system)}
  1343. module, and actual build systems are exported by specific modules.
  1344. @cindex bag (low-level package representation)
  1345. Under the hood, build systems first compile package objects to
  1346. @dfn{bags}. A @dfn{bag} is like a package, but with less
  1347. ornamentation---in other words, a bag is a lower-level representation of
  1348. a package, which includes all the inputs of that package, including some
  1349. that were implicitly added by the build system. This intermediate
  1350. representation is then compiled to a derivation (@pxref{Derivations}).
  1351. Build systems accept an optional list of @dfn{arguments}. In package
  1352. definitions, these are passed @i{via} the @code{arguments} field
  1353. (@pxref{Defining Packages}). They are typically keyword arguments
  1354. (@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
  1355. Guile Reference Manual}). The value of these arguments is usually
  1356. evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
  1357. by the daemon (@pxref{Derivations}).
  1358. The main build system is @var{gnu-build-system}, which implements the
  1359. standard build procedure for GNU packages and many other packages. It
  1360. is provided by the @code{(guix build-system gnu)} module.
  1361. @defvr {Scheme Variable} gnu-build-system
  1362. @var{gnu-build-system} represents the GNU Build System, and variants
  1363. thereof (@pxref{Configuration, configuration and makefile conventions,,
  1364. standards, GNU Coding Standards}).
  1365. @cindex build phases
  1366. In a nutshell, packages using it configured, built, and installed with
  1367. the usual @code{./configure && make && make check && make install}
  1368. command sequence. In practice, a few additional steps are often needed.
  1369. All these steps are split up in separate @dfn{phases},
  1370. notably@footnote{Please see the @code{(guix build gnu-build-system)}
  1371. modules for more details about the build phases.}:
  1372. @table @code
  1373. @item unpack
  1374. Unpack the source tarball, and change the current directory to the
  1375. extracted source tree. If the source is actually a directory, copy it
  1376. to the build tree, and enter that directory.
  1377. @item patch-source-shebangs
  1378. Patch shebangs encountered in source files so they refer to the right
  1379. store file names. For instance, this changes @code{#!/bin/sh} to
  1380. @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
  1381. @item configure
  1382. Run the @file{configure} script with a number of default options, such
  1383. as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
  1384. by the @code{#:configure-flags} argument.
  1385. @item build
  1386. Run @code{make} with the list of flags specified with
  1387. @code{#:make-flags}. If the @code{#:parallel-builds?} argument is true
  1388. (the default), build with @code{make -j}.
  1389. @item check
  1390. Run @code{make check}, or some other target specified with
  1391. @code{#:test-target}, unless @code{#:tests? #f} is passed. If the
  1392. @code{#:parallel-tests?} argument is true (the default), run @code{make
  1393. check -j}.
  1394. @item install
  1395. Run @code{make install} with the flags listed in @code{#:make-flags}.
  1396. @item patch-shebangs
  1397. Patch shebangs on the installed executable files.
  1398. @item strip
  1399. Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
  1400. is false), copying them to the @code{debug} output when available
  1401. (@pxref{Installing Debugging Files}).
  1402. @end table
  1403. @vindex %standard-phases
  1404. The build-side module @code{(guix build gnu-build-system)} defines
  1405. @var{%standard-phases} as the default list of build phases.
  1406. @var{%standard-phases} is a list of symbol/procedure pairs, where the
  1407. procedure implements the actual phase.
  1408. The list of phases used for a particular package can be changed with the
  1409. @code{#:phases} parameter. For instance, passing:
  1410. @example
  1411. #:phases (alist-delete 'configure %standard-phases)
  1412. @end example
  1413. means that all the phases described above will be used, except the
  1414. @code{configure} phase.
  1415. In addition, this build system ensures that the ``standard'' environment
  1416. for GNU packages is available. This includes tools such as GCC, libc,
  1417. Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
  1418. build-system gnu)} module for a complete list.) We call these the
  1419. @dfn{implicit inputs} of a package, because package definitions don't
  1420. have to mention them.
  1421. @end defvr
  1422. Other @code{<build-system>} objects are defined to support other
  1423. conventions and tools used by free software packages. They inherit most
  1424. of @var{gnu-build-system}, and differ mainly in the set of inputs
  1425. implicitly added to the build process, and in the list of phases
  1426. executed. Some of these build systems are listed below.
  1427. @defvr {Scheme Variable} cmake-build-system
  1428. This variable is exported by @code{(guix build-system cmake)}. It
  1429. implements the build procedure for packages using the
  1430. @url{, CMake build tool}.
  1431. It automatically adds the @code{cmake} package to the set of inputs.
  1432. Which package is used can be specified with the @code{#:cmake}
  1433. parameter.
  1434. The @code{#:configure-flags} parameter is taken as a list of flags
  1435. passed to the @command{cmake} command. The @code{#:build-type}
  1436. parameter specifies in abstract terms the flags passed to the compiler;
  1437. it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
  1438. debugging information''), which roughly means that code is compiled with
  1439. @code{-O2 -g}, as is the case for Autoconf-based packages by default.
  1440. @end defvr
  1441. @defvr {Scheme Variable} glib-or-gtk-build-system
  1442. This variable is exported by @code{(guix build-system glib-or-gtk)}. It
  1443. is intended for use with packages making use of GLib or GTK+.
  1444. This build system adds the following two phases to the ones defined by
  1445. @var{gnu-build-system}:
  1446. @table @code
  1447. @item glib-or-gtk-wrap
  1448. The phase @code{glib-or-gtk-wrap} ensures that programs found under
  1449. @file{bin/} are able to find GLib's ``schemas'' and
  1450. @uref{, GTK+
  1451. modules}. This is achieved by wrapping the programs in launch scripts
  1452. that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
  1453. environment variables.
  1454. It is possible to exclude specific package outputs from that wrapping
  1455. process by listing their names in the
  1456. @code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
  1457. when an output is known not to contain any GLib or GTK+ binaries, and
  1458. where wrapping would gratuitously add a dependency of that output on
  1459. GLib and GTK+.
  1460. @item glib-or-gtk-compile-schemas
  1461. The phase @code{glib-or-gtk-compile-schemas} makes sure that all GLib's
  1462. @uref{,
  1463. GSettings schemas} are compiled. Compilation is performed by the
  1464. @command{glib-compile-schemas} program. It is provided by the package
  1465. @code{glib:bin} which is automatically imported by the build system.
  1466. The @code{glib} package providing @command{glib-compile-schemas} can be
  1467. specified with the @code{#:glib} parameter.
  1468. @end table
  1469. Both phases are executed after the @code{install} phase.
  1470. @end defvr
  1471. @defvr {Scheme Variable} python-build-system
  1472. This variable is exported by @code{(guix build-system python)}. It
  1473. implements the more or less standard build procedure used by Python
  1474. packages, which consists in running @code{python build} and
  1475. then @code{python install --prefix=/gnu/store/@dots{}}.
  1476. For packages that install stand-alone Python programs under @code{bin/},
  1477. it takes care of wrapping these programs so their @code{PYTHONPATH}
  1478. environment variable points to all the Python libraries they depend on.
  1479. Which Python package is used can be specified with the @code{#:python}
  1480. parameter.
  1481. @end defvr
  1482. @defvr {Scheme Variable} perl-build-system
  1483. This variable is exported by @code{(guix build-system perl)}. It
  1484. implements the standard build procedure for Perl packages, which
  1485. consists in running @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}},
  1486. followed by @code{make} and @code{make install}.
  1487. The initial @code{perl Makefile.PL} invocation passes flags specified by
  1488. the @code{#:make-maker-flags} parameter.
  1489. Which Perl package is used can be specified with @code{#:perl}.
  1490. @end defvr
  1491. @defvr {Scheme Variable} ruby-build-system
  1492. This variable is exported by @code{(guix build-system ruby)}. It
  1493. implements the RubyGems build procedure used by Ruby packages, which
  1494. involves running @code{gem build} followed by @code{gem install}.
  1495. Which Ruby package is used can be specified with the @code{#:ruby}
  1496. parameter.
  1497. @end defvr
  1498. Lastly, for packages that do not need anything as sophisticated, a
  1499. ``trivial'' build system is provided. It is trivial in the sense that
  1500. it provides basically no support: it does not pull any implicit inputs,
  1501. and does not have a notion of build phases.
  1502. @defvr {Scheme Variable} trivial-build-system
  1503. This variable is exported by @code{(guix build-system trivial)}.
  1504. This build system requires a @code{#:builder} argument. This argument
  1505. must be a Scheme expression that builds the package's output(s)---as
  1506. with @code{build-expression->derivation} (@pxref{Derivations,
  1507. @code{build-expression->derivation}}).
  1508. @end defvr
  1509. @node The Store
  1510. @section The Store
  1511. @cindex store
  1512. @cindex store paths
  1513. Conceptually, the @dfn{store} is where derivations that have been
  1514. successfully built are stored---by default, under @file{/gnu/store}.
  1515. Sub-directories in the store are referred to as @dfn{store paths}. The
  1516. store has an associated database that contains information such has the
  1517. store paths referred to by each store path, and the list of @emph{valid}
  1518. store paths---paths that result from a successful build.
  1519. The store is always accessed by the daemon on behalf of its clients
  1520. (@pxref{Invoking guix-daemon}). To manipulate the store, clients
  1521. connect to the daemon over a Unix-domain socket, send it requests, and
  1522. read the result---these are remote procedure calls, or RPCs.
  1523. The @code{(guix store)} module provides procedures to connect to the
  1524. daemon, and to perform RPCs. These are described below.
  1525. @deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
  1526. Connect to the daemon over the Unix-domain socket at @var{file}. When
  1527. @var{reserve-space?} is true, instruct it to reserve a little bit of
  1528. extra space on the file system so that the garbage collector can still
  1529. operate, should the disk become full. Return a server object.
  1530. @var{file} defaults to @var{%default-socket-path}, which is the normal
  1531. location given the options that were passed to @command{configure}.
  1532. @end deffn
  1533. @deffn {Scheme Procedure} close-connection @var{server}
  1534. Close the connection to @var{server}.
  1535. @end deffn
  1536. @defvr {Scheme Variable} current-build-output-port
  1537. This variable is bound to a SRFI-39 parameter, which refers to the port
  1538. where build and error logs sent by the daemon should be written.
  1539. @end defvr
  1540. Procedures that make RPCs all take a server object as their first
  1541. argument.
  1542. @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
  1543. Return @code{#t} when @var{path} is a valid store path.
  1544. @end deffn
  1545. @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
  1546. Add @var{text} under file @var{name} in the store, and return its store
  1547. path. @var{references} is the list of store paths referred to by the
  1548. resulting store path.
  1549. @end deffn
  1550. @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
  1551. Build @var{derivations} (a list of @code{<derivation>} objects or
  1552. derivation paths), and return when the worker is done building them.
  1553. Return @code{#t} on success.
  1554. @end deffn
  1555. Note that the @code{(guix monads)} module provides a monad as well as
  1556. monadic versions of the above procedures, with the goal of making it
  1557. more convenient to work with code that accesses the store (@pxref{The
  1558. Store Monad}).
  1559. @c FIXME
  1560. @i{This section is currently incomplete.}
  1561. @node Derivations
  1562. @section Derivations
  1563. @cindex derivations
  1564. Low-level build actions and the environment in which they are performed
  1565. are represented by @dfn{derivations}. A derivation contain the
  1566. following pieces of information:
  1567. @itemize
  1568. @item
  1569. The outputs of the derivation---derivations produce at least one file or
  1570. directory in the store, but may produce more.
  1571. @item
  1572. The inputs of the derivations, which may be other derivations or plain
  1573. files in the store (patches, build scripts, etc.)
  1574. @item
  1575. The system type targeted by the derivation---e.g., @code{x86_64-linux}.
  1576. @item
  1577. The file name of a build script in the store, along with the arguments
  1578. to be passed.
  1579. @item
  1580. A list of environment variables to be defined.
  1581. @end itemize
  1582. @cindex derivation path
  1583. Derivations allow clients of the daemon to communicate build actions to
  1584. the store. They exist in two forms: as an in-memory representation,
  1585. both on the client- and daemon-side, and as files in the store whose
  1586. name end in @code{.drv}---these files are referred to as @dfn{derivation
  1587. paths}. Derivations paths can be passed to the @code{build-derivations}
  1588. procedure to perform the build actions they prescribe (@pxref{The
  1589. Store}).
  1590. The @code{(guix derivations)} module provides a representation of
  1591. derivations as Scheme objects, along with procedures to create and
  1592. otherwise manipulate derivations. The lowest-level primitive to create
  1593. a derivation is the @code{derivation} procedure:
  1594. @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
  1595. @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
  1596. [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
  1597. [#:system (%current-system)] [#:references-graphs #f] @
  1598. [#:allowed-references #f] [#:local-build? #f]
  1599. Build a derivation with the given arguments, and return the resulting
  1600. @code{<derivation>} object.
  1601. When @var{hash} and @var{hash-algo} are given, a
  1602. @dfn{fixed-output derivation} is created---i.e., one whose result is
  1603. known in advance, such as a file download. If, in addition,
  1604. @var{recursive?} is true, then that fixed output may be an executable
  1605. file or a directory and @var{hash} must be the hash of an archive
  1606. containing this output.
  1607. When @var{references-graphs} is true, it must be a list of file
  1608. name/store path pairs. In that case, the reference graph of each store
  1609. path is exported in the build environment in the corresponding file, in
  1610. a simple text format.
  1611. When @var{allowed-references} is true, it must be a list of store items
  1612. or outputs that the derivation's output may refer to.
  1613. When @var{local-build?} is true, declare that the derivation is not a
  1614. good candidate for offloading and should rather be built locally
  1615. (@pxref{Daemon Offload Setup}). This is the case for small derivations
  1616. where the costs of data transfers would outweigh the benefits.
  1617. @end deffn
  1618. @noindent
  1619. Here's an example with a shell script as its builder, assuming
  1620. @var{store} is an open connection to the daemon, and @var{bash} points
  1621. to a Bash executable in the store:
  1622. @lisp
  1623. (use-modules (guix utils)
  1624. (guix store)
  1625. (guix derivations))
  1626. (let ((builder ; add the Bash script to the store
  1627. (add-text-to-store store ""
  1628. "echo hello world > $out\n" '())))
  1629. (derivation store "foo"
  1630. bash `("-e" ,builder)
  1631. #:inputs `((,bash) (,builder))
  1632. #:env-vars '(("HOME" . "/homeless"))))
  1633. @result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
  1634. @end lisp
  1635. As can be guessed, this primitive is cumbersome to use directly. A
  1636. better approach is to write build scripts in Scheme, of course! The
  1637. best course of action for that is to write the build code as a
  1638. ``G-expression'', and to pass it to @code{gexp->derivation}. For more
  1639. information, @pxref{G-Expressions}.
  1640. Once upon a time, @code{gexp->derivation} did not exist and constructing
  1641. derivations with build code written in Scheme was achieved with
  1642. @code{build-expression->derivation}, documented below. This procedure
  1643. is now deprecated in favor of the much nicer @code{gexp->derivation}.
  1644. @deffn {Scheme Procedure} build-expression->derivation @var{store} @
  1645. @var{name} @var{exp} @
  1646. [#:system (%current-system)] [#:inputs '()] @
  1647. [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
  1648. [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
  1649. [#:references-graphs #f] [#:allowed-references #f] @
  1650. [#:local-build? #f] [#:guile-for-build #f]
  1651. Return a derivation that executes Scheme expression @var{exp} as a
  1652. builder for derivation @var{name}. @var{inputs} must be a list of
  1653. @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
  1654. @code{"out"} is assumed. @var{modules} is a list of names of Guile
  1655. modules from the current search path to be copied in the store,
  1656. compiled, and made available in the load path during the execution of
  1657. @var{exp}---e.g., @code{((guix build utils) (guix build
  1658. gnu-build-system))}.
  1659. @var{exp} is evaluated in an environment where @code{%outputs} is bound
  1660. to a list of output/path pairs, and where @code{%build-inputs} is bound
  1661. to a list of string/output-path pairs made from @var{inputs}.
  1662. Optionally, @var{env-vars} is a list of string pairs specifying the name
  1663. and value of environment variables visible to the builder. The builder
  1664. terminates by passing the result of @var{exp} to @code{exit}; thus, when
  1665. @var{exp} returns @code{#f}, the build is considered to have failed.
  1666. @var{exp} is built using @var{guile-for-build} (a derivation). When
  1667. @var{guile-for-build} is omitted or is @code{#f}, the value of the
  1668. @code{%guile-for-build} fluid is used instead.
  1669. See the @code{derivation} procedure for the meaning of
  1670. @var{references-graphs}, @var{allowed-references}, and @var{local-build?}.
  1671. @end deffn
  1672. @noindent
  1673. Here's an example of a single-output derivation that creates a directory
  1674. containing one file:
  1675. @lisp
  1676. (let ((builder '(let ((out (assoc-ref %outputs "out")))
  1677. (mkdir out) ; create /gnu/store/@dots{}-goo
  1678. (call-with-output-file (string-append out "/test")
  1679. (lambda (p)
  1680. (display '(hello guix) p))))))
  1681. (build-expression->derivation store "goo" builder))
  1682. @result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
  1683. @end lisp
  1684. @node The Store Monad
  1685. @section The Store Monad
  1686. @cindex monad
  1687. The procedures that operate on the store described in the previous
  1688. sections all take an open connection to the build daemon as their first
  1689. argument. Although the underlying model is functional, they either have
  1690. side effects or depend on the current state of the store.
  1691. The former is inconvenient: the connection to the build daemon has to be
  1692. carried around in all those functions, making it impossible to compose
  1693. functions that do not take that parameter with functions that do. The
  1694. latter can be problematic: since store operations have side effects
  1695. and/or depend on external state, they have to be properly sequenced.
  1696. @cindex monadic values
  1697. @cindex monadic functions
  1698. This is where the @code{(guix monads)} module comes in. This module
  1699. provides a framework for working with @dfn{monads}, and a particularly
  1700. useful monad for our uses, the @dfn{store monad}. Monads are a
  1701. construct that allows two things: associating ``context'' with values
  1702. (in our case, the context is the store), and building sequences of
  1703. computations (here computations includes accesses to the store.) Values
  1704. in a monad---values that carry this additional context---are called
  1705. @dfn{monadic values}; procedures that return such values are called
  1706. @dfn{monadic procedures}.
  1707. Consider this ``normal'' procedure:
  1708. @example
  1709. (define (sh-symlink store)
  1710. ;; Return a derivation that symlinks the 'bash' executable.
  1711. (let* ((drv (package-derivation store bash))
  1712. (out (derivation->output-path drv))
  1713. (sh (string-append out "/bin/bash")))
  1714. (build-expression->derivation store "sh"
  1715. `(symlink ,sh %output))))
  1716. @end example
  1717. Using @code{(guix monads)}, it may be rewritten as a monadic function:
  1718. @c FIXME: Find a better example, one that uses 'mlet'.
  1719. @example
  1720. (define (sh-symlink)
  1721. ;; Same, but return a monadic value.
  1722. (gexp->derivation "sh"
  1723. #~(symlink (string-append #$bash "/bin/bash") #$output)))
  1724. @end example
  1725. There are two things to note in the second version: the @code{store}
  1726. parameter is now implicit, and the monadic value returned by
  1727. @code{package-file}---a wrapper around @code{package-derivation} and
  1728. @code{derivation->output-path}---is @dfn{bound} using @code{mlet}
  1729. instead of plain @code{let}.
  1730. Calling the monadic @code{} has no effect. To get the desired
  1731. effect, one must use @code{run-with-store}:
  1732. @example
  1733. (run-with-store (open-connection) (
  1734. @result{} /gnu/store/
  1735. @end example
  1736. Note that the @code{(guix monad-repl)} module extends Guile's REPL with
  1737. new ``meta-commands'' to make it easier to deal with monadic procedures:
  1738. @code{run-in-store}, and @code{enter-store-monad}. The former, is used
  1739. to ``run'' a single monadic value through the store:
  1740. @example
  1741. scheme@@(guile-user)> ,run-in-store (package->derivation hello)
  1742. $1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
  1743. @end example
  1744. The latter enters a recursive REPL, where all the return values are
  1745. automatically run through the store:
  1746. @example
  1747. scheme@@(guile-user)> ,enter-store-monad
  1748. store-monad@@(guile-user) [1]> (package->derivation hello)
  1749. $2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
  1750. store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
  1751. $3 = "/gnu/store/@dots{}-foo"
  1752. store-monad@@(guile-user) [1]> ,q
  1753. scheme@@(guile-user)>
  1754. @end example
  1755. @noindent
  1756. Note that non-monadic values cannot be returned in the
  1757. @code{store-monad} REPL.
  1758. The main syntactic forms to deal with monads in general are described
  1759. below.
  1760. @deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
  1761. Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
  1762. in @var{monad}.
  1763. @end deffn
  1764. @deffn {Scheme Syntax} return @var{val}
  1765. Return a monadic value that encapsulates @var{val}.
  1766. @end deffn
  1767. @deffn {Scheme Syntax} >>= @var{mval} @var{mproc}
  1768. @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
  1769. procedure @var{mproc}@footnote{This operation is commonly referred to as
  1770. ``bind'', but that name denotes an unrelated procedure in Guile. Thus
  1771. we use this somewhat cryptic symbol inherited from the Haskell
  1772. language.}.
  1773. @end deffn
  1774. @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
  1775. @var{body} ...
  1776. @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
  1777. @var{body} ...
  1778. Bind the variables @var{var} to the monadic values @var{mval} in
  1779. @var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the
  1780. ``normal'' value @var{val}, as per @code{let}.
  1781. @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
  1782. (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
  1783. @end deffn
  1784. @deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
  1785. Bind @var{mexp} and the following monadic expressions in sequence,
  1786. returning the result of the last expression.
  1787. This is akin to @code{mlet}, except that the return values of the
  1788. monadic expressions are ignored. In that sense, it is analogous to
  1789. @code{begin}, but applied to monadic expressions.
  1790. @end deffn
  1791. The interface to the store monad provided by @code{(guix monads)} is as
  1792. follows.
  1793. @defvr {Scheme Variable} %store-monad
  1794. The store monad. Values in the store monad encapsulate accesses to the
  1795. store. When its effect is needed, a value of the store monad must be
  1796. ``evaluated'' by passing it to the @code{run-with-store} procedure (see
  1797. below.)
  1798. @end defvr
  1799. @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
  1800. Run @var{mval}, a monadic value in the store monad, in @var{store}, an
  1801. open store connection.
  1802. @end deffn
  1803. @deffn {Monadic Procedure} text-file @var{name} @var{text}
  1804. Return as a monadic value the absolute file name in the store of the file
  1805. containing @var{text}, a string.
  1806. @end deffn
  1807. @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
  1808. Return as a monadic value a derivation that builds a text file
  1809. containing all of @var{text}. @var{text} may list, in addition to
  1810. strings, packages, derivations, and store file names; the resulting
  1811. store file holds references to all these.
  1812. This variant should be preferred over @code{text-file} anytime the file
  1813. to create will reference items from the store. This is typically the
  1814. case when building a configuration file that embeds store file names,
  1815. like this:
  1816. @example
  1817. (define (
  1818. ;; Return the name of a shell script in the store that
  1819. ;; initializes the 'PATH' environment variable.
  1820. (text-file* ""
  1821. "export PATH=" coreutils "/bin:"
  1822. grep "/bin:" sed "/bin\n"))
  1823. @end example
  1824. In this example, the resulting @file{/gnu/store/@dots{}} file
  1825. will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
  1826. preventing them from being garbage-collected during its lifetime.
  1827. @end deffn
  1828. @deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
  1829. [#:recursive? #t]
  1830. Return the name of @var{file} once interned in the store. Use
  1831. @var{name} as its store name, or the basename of @var{file} if
  1832. @var{name} is omitted.
  1833. When @var{recursive?} is true, the contents of @var{file} are added
  1834. recursively; if @var{file} designates a flat file and @var{recursive?}
  1835. is true, its contents are added, and its permission bits are kept.
  1836. The example below adds a file to the store, under two different names:
  1837. @example
  1838. (run-with-store (open-connection)
  1839. (mlet %store-monad ((a (interned-file "README"))
  1840. (b (interned-file "README" "LEGU-MIN")))
  1841. (return (list a b))))
  1842. @result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
  1843. @end example
  1844. @end deffn
  1845. @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
  1846. [#:system (%current-system)] [#:target #f] @
  1847. [#:output "out"] Return as a monadic
  1848. value in the absolute file name of @var{file} within the @var{output}
  1849. directory of @var{package}. When @var{file} is omitted, return the name
  1850. of the @var{output} directory of @var{package}. When @var{target} is
  1851. true, use it as a cross-compilation target triplet.
  1852. @end deffn
  1853. @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
  1854. @deffnx {Monadic Procedure} package->cross-derivation @var{package} @
  1855. @var{target} [@var{system}]
  1856. Monadic version of @code{package-derivation} and
  1857. @code{package-cross-derivation} (@pxref{Defining Packages}).
  1858. @end deffn
  1859. @node G-Expressions
  1860. @section G-Expressions
  1861. @cindex G-expression
  1862. @cindex build code quoting
  1863. So we have ``derivations'', which represent a sequence of build actions
  1864. to be performed to produce an item in the store (@pxref{Derivations}).
  1865. Those build actions are performed when asking the daemon to actually
  1866. build the derivations; they are run by the daemon in a container
  1867. (@pxref{Invoking guix-daemon}).
  1868. @cindex strata of code
  1869. It should come as no surprise that we like to write those build actions
  1870. in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
  1871. code@footnote{The term @dfn{stratum} in this context was coined by
  1872. Manuel Serrano et al.@: in the context of their work on Hop. Oleg
  1873. Kiselyov, who has written insightful
  1874. @url{, essays and code
  1875. on this topic}, refers to this kind of code generation as
  1876. @dfn{staging}.}: the ``host code''---code that defines packages, talks
  1877. to the daemon, etc.---and the ``build code''---code that actually
  1878. performs build actions, such as making directories, invoking
  1879. @command{make}, etc.
  1880. To describe a derivation and its build actions, one typically needs to
  1881. embed build code inside host code. It boils down to manipulating build
  1882. code as data, and Scheme's homoiconicity---code has a direct
  1883. representation as data---comes in handy for that. But we need more than
  1884. Scheme's normal @code{quasiquote} mechanism to construct build
  1885. expressions.
  1886. The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
  1887. S-expressions adapted to build expressions. G-expressions, or
  1888. @dfn{gexps}, consist essentially in three syntactic forms: @code{gexp},
  1889. @code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
  1890. @code{#$}, and @code{#$@@}), which are comparable respectively to
  1891. @code{quasiquote}, @code{unquote}, and @code{unquote-splicing}
  1892. (@pxref{Expression Syntax, @code{quasiquote},, guile, GNU Guile
  1893. Reference Manual}). However, there are major differences:
  1894. @itemize
  1895. @item
  1896. Gexps are meant to be written to a file and run or manipulated by other
  1897. processes.
  1898. @item
  1899. When a package or derivation is unquoted inside a gexp, the result is as
  1900. if its output file name had been introduced.
  1901. @item
  1902. Gexps carry information about the packages or derivations they refer to,
  1903. and these dependencies are automatically added as inputs to the build
  1904. processes that use them.
  1905. @end itemize
  1906. To illustrate the idea, here is an example of a gexp:
  1907. @example
  1908. (define build-exp
  1909. #~(begin
  1910. (mkdir #$output)
  1911. (chdir #$output)
  1912. (symlink (string-append #$coreutils "/bin/ls")
  1913. "list-files")))
  1914. @end example
  1915. This gexp can be passed to @code{gexp->derivation}; we obtain a
  1916. derivation that builds a directory containing exactly one symlink to
  1917. @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
  1918. @example
  1919. (gexp->derivation "the-thing" build-exp)
  1920. @end example
  1921. As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
  1922. substituted to the reference to the @var{coreutils} package in the
  1923. actual build code, and @var{coreutils} is automatically made an input to
  1924. the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
  1925. output)}) is replaced by a string containing the derivation's output
  1926. directory name.
  1927. @cindex cross compilation
  1928. In a cross-compilation context, it is useful to distinguish between
  1929. references to the @emph{native} build of a package---that can run on the
  1930. host---versus references to cross builds of a package. To that end, the
  1931. @code{#+} plays the same role as @code{#$}, but is a reference to a
  1932. native package build:
  1933. @example
  1934. (gexp->derivation "vi"
  1935. #~(begin
  1936. (mkdir #$output)
  1937. (system* (string-append #+coreutils "/bin/ln")
  1938. "-s"
  1939. (string-append #$emacs "/bin/emacs")
  1940. (string-append #$output "/bin/vi")))
  1941. #:target "mips64el-linux")
  1942. @end example
  1943. @noindent
  1944. In the example above, the native build of @var{coreutils} is used, so
  1945. that @command{ln} can actually run on the host; but then the
  1946. cross-compiled build of @var{emacs} is referenced.
  1947. The syntactic form to construct gexps is summarized below.
  1948. @deffn {Scheme Syntax} #~@var{exp}
  1949. @deffnx {Scheme Syntax} (gexp @var{exp})
  1950. Return a G-expression containing @var{exp}. @var{exp} may contain one
  1951. or more of the following forms:
  1952. @table @code
  1953. @item #$@var{obj}
  1954. @itemx (ungexp @var{obj})
  1955. Introduce a reference to @var{obj}. @var{obj} may be a package or a
  1956. derivation, in which case the @code{ungexp} form is replaced by its
  1957. output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
  1958. If @var{obj} is a list, it is traversed and any package or derivation
  1959. references are substituted similarly.
  1960. If @var{obj} is another gexp, its contents are inserted and its
  1961. dependencies are added to those of the containing gexp.
  1962. If @var{obj} is another kind of object, it is inserted as is.
  1963. @item #$@var{package-or-derivation}:@var{output}
  1964. @itemx (ungexp @var{package-or-derivation} @var{output})
  1965. This is like the form above, but referring explicitly to the
  1966. @var{output} of @var{package-or-derivation}---this is useful when
  1967. @var{package-or-derivation} produces multiple outputs (@pxref{Packages
  1968. with Multiple Outputs}).
  1969. @item #+@var{obj}
  1970. @itemx #+@var{obj}:output
  1971. @itemx (ungexp-native @var{obj})
  1972. @itemx (ungexp-native @var{obj} @var{output})
  1973. Same as @code{ungexp}, but produces a reference to the @emph{native}
  1974. build of @var{obj} when used in a cross compilation context.
  1975. @item #$output[:@var{output}]
  1976. @itemx (ungexp output [@var{output}])
  1977. Insert a reference to derivation output @var{output}, or to the main
  1978. output when @var{output} is omitted.
  1979. This only makes sense for gexps passed to @code{gexp->derivation}.
  1980. @item #$@@@var{lst}
  1981. @itemx (ungexp-splicing @var{lst})
  1982. Like the above, but splices the contents of @var{lst} inside the
  1983. containing list.
  1984. @item #+@@@var{lst}
  1985. @itemx (ungexp-native-splicing @var{lst})
  1986. Like the above, but refers to native builds of the objects listed in
  1987. @var{lst}.
  1988. @end table
  1989. G-expressions created by @code{gexp} or @code{#~} are run-time objects
  1990. of the @code{gexp?} type (see below.)
  1991. @end deffn
  1992. @deffn {Scheme Procedure} gexp? @var{obj}
  1993. Return @code{#t} if @var{obj} is a G-expression.
  1994. @end deffn
  1995. G-expressions are meant to be written to disk, either as code building
  1996. some derivation, or as plain files in the store. The monadic procedures
  1997. below allow you to do that (@pxref{The Store Monad}, for more
  1998. information about monads.)
  1999. @deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
  2000. [#:system (%current-system)] [#:target #f] [#:inputs '()] @
  2001. [#:hash #f] [#:hash-algo #f] @
  2002. [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
  2003. [#:module-path @var{%load-path}] @
  2004. [#:references-graphs #f] [#:local-build? #f] @
  2005. [#:guile-for-build #f]
  2006. Return a derivation @var{name} that runs @var{exp} (a gexp) with
  2007. @var{guile-for-build} (a derivation) on @var{system}. When @var{target}
  2008. is true, it is used as the cross-compilation target triplet for packages
  2009. referred to by @var{exp}.
  2010. Make @var{modules} available in the evaluation context of @var{EXP};
  2011. @var{MODULES} is a list of names of Guile modules searched in
  2012. @var{MODULE-PATH} to be copied in the store, compiled, and made available in
  2013. the load path during the execution of @var{exp}---e.g., @code{((guix
  2014. build utils) (guix build gnu-build-system))}.
  2015. When @var{references-graphs} is true, it must be a list of tuples of one of the
  2016. following forms:
  2017. @example
  2018. (@var{file-name} @var{package})
  2019. (@var{file-name} @var{package} @var{output})
  2020. (@var{file-name} @var{derivation})
  2021. (@var{file-name} @var{derivation} @var{output})
  2022. (@var{file-name} @var{store-item})
  2023. @end example
  2024. The right-hand-side of each element of @var{references-graphs} is automatically made
  2025. an input of the build process of @var{exp}. In the build environment, each
  2026. @var{file-name} contains the reference graph of the corresponding item, in a simple
  2027. text format.
  2028. The other arguments are as for @code{derivation} (@pxref{Derivations}).
  2029. @end deffn
  2030. @deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
  2031. Return an executable script @var{name} that runs @var{exp} using
  2032. @var{guile} with @var{modules} in its search path.
  2033. The example below builds a script that simply invokes the @command{ls}
  2034. command:
  2035. @example
  2036. (use-modules (guix gexp) (gnu packages base))
  2037. (gexp->script "list-files"
  2038. #~(execl (string-append #$coreutils "/bin/ls")
  2039. "ls"))
  2040. @end example
  2041. When ``running'' it through the store (@pxref{The Store Monad,
  2042. @code{run-with-store}}), we obtain a derivation that produces an
  2043. executable file @file{/gnu/store/@dots{}-list-files} along these lines:
  2044. @example
  2045. #!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
  2046. !#
  2047. (execl (string-append "/gnu/store/@dots{}-coreutils-8.22"/bin/ls")
  2048. "ls")
  2049. @end example
  2050. @end deffn
  2051. @deffn {Monadic Procedure} gexp->file @var{name} @var{exp}
  2052. Return a derivation that builds a file @var{name} containing @var{exp}.
  2053. The resulting file holds references to all the dependencies of @var{exp}
  2054. or a subset thereof.
  2055. @end deffn
  2056. Of course, in addition to gexps embedded in ``host'' code, there are
  2057. also modules containing build tools. To make it clear that they are
  2058. meant to be used in the build stratum, these modules are kept in the
  2059. @code{(guix build @dots{})} name space.
  2060. @c *********************************************************************
  2061. @node Utilities
  2062. @chapter Utilities
  2063. This section describes tools primarily targeted at developers and users
  2064. who write new package definitions. They complement the Scheme
  2065. programming interface of Guix in a convenient way.
  2066. @menu
  2067. * Invoking guix build:: Building packages from the command line.
  2068. * Invoking guix download:: Downloading a file and printing its hash.
  2069. * Invoking guix hash:: Computing the cryptographic hash of a file.
  2070. * Invoking guix import:: Importing package definitions.
  2071. * Invoking guix refresh:: Updating package definitions.
  2072. * Invoking guix lint:: Finding errors in package definitions.
  2073. * Invoking guix environment:: Setting up development environments.
  2074. @end menu
  2075. @node Invoking guix build
  2076. @section Invoking @command{guix build}
  2077. The @command{guix build} command builds packages or derivations and
  2078. their dependencies, and prints the resulting store paths. Note that it
  2079. does not modify the user's profile---this is the job of the
  2080. @command{guix package} command (@pxref{Invoking guix package}). Thus,
  2081. it is mainly useful for distribution developers.
  2082. The general syntax is:
  2083. @example
  2084. guix build @var{options} @var{package-or-derivation}@dots{}
  2085. @end example
  2086. @var{package-or-derivation} may be either the name of a package found in
  2087. the software distribution such as @code{coreutils} or
  2088. @code{coreutils-8.20}, or a derivation such as
  2089. @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
  2090. package with the corresponding name (and optionally version) is searched
  2091. for among the GNU distribution modules (@pxref{Package Modules}).
  2092. Alternatively, the @code{--expression} option may be used to specify a
  2093. Scheme expression that evaluates to a package; this is useful when
  2094. disambiguation among several same-named packages or package variants is
  2095. needed.
  2096. The @var{options} may be zero or more of the following:
  2097. @table @code
  2098. @item --expression=@var{expr}
  2099. @itemx -e @var{expr}
  2100. Build the package or derivation @var{expr} evaluates to.
  2101. For example, @var{expr} may be @code{(@@ (gnu packages guile)
  2102. guile-1.8)}, which unambiguously designates this specific variant of
  2103. version 1.8 of Guile.
  2104. Alternately, @var{expr} may be a G-expression, in which case it is used
  2105. as a build program passed to @code{gexp->derivation}
  2106. (@pxref{G-Expressions}).
  2107. Lastly, @var{expr} may refer to a zero-argument monadic procedure
  2108. (@pxref{The Store Monad}). The procedure must return a derivation as a
  2109. monadic value, which is then passed through @code{run-with-store}.
  2110. @item --source
  2111. @itemx -S
  2112. Build the packages' source derivations, rather than the packages
  2113. themselves.
  2114. For instance, @code{guix build -S gcc} returns something like
  2115. @file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
  2116. The returned source tarball is the result of applying any patches and
  2117. code snippets specified in the package's @code{origin} (@pxref{Defining
  2118. Packages}).
  2119. @item --system=@var{system}
  2120. @itemx -s @var{system}
  2121. Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
  2122. the host's system type.
  2123. An example use of this is on Linux-based systems, which can emulate
  2124. different personalities. For instance, passing
  2125. @code{--system=i686-linux} on an @code{x86_64-linux} system allows users
  2126. to build packages in a complete 32-bit environment.
  2127. @item --target=@var{triplet}
  2128. @cindex cross-compilation
  2129. Cross-build for @var{triplet}, which must be a valid GNU triplet, such
  2130. as @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU
  2131. configuration triplets,, configure, GNU Configure and Build System}).
  2132. @item --with-source=@var{source}
  2133. Use @var{source} as the source of the corresponding package.
  2134. @var{source} must be a file name or a URL, as for @command{guix
  2135. download} (@pxref{Invoking guix download}).
  2136. The ``corresponding package'' is taken to be one specified on the
  2137. command line whose name matches the base of @var{source}---e.g., if
  2138. @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
  2139. package is @code{guile}. Likewise, the version string is inferred from
  2140. @var{source}; in the previous example, it's @code{2.0.10}.
  2141. This option allows users to try out versions of packages other than the
  2142. one provided by the distribution. The example below downloads
  2143. @file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
  2144. the @code{ed} package:
  2145. @example
  2146. guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
  2147. @end example
  2148. As a developer, @code{--with-source} makes it easy to test release
  2149. candidates:
  2150. @example
  2151. guix build guile --with-source=../guile-
  2152. @end example
  2153. @item --no-grafts
  2154. Do not ``graft'' packages. In practice, this means that package updates
  2155. available as grafts are not applied. @xref{Security Updates}, for more
  2156. information on grafts.
  2157. @item --derivations
  2158. @itemx -d
  2159. Return the derivation paths, not the output paths, of the given
  2160. packages.
  2161. @item --root=@var{file}
  2162. @itemx -r @var{file}
  2163. Make @var{file} a symlink to the result, and register it as a garbage
  2164. collector root.
  2165. @item --log-file
  2166. Return the build log file names for the given
  2167. @var{package-or-derivation}s, or raise an error if build logs are
  2168. missing.
  2169. This works regardless of how packages or derivations are specified. For
  2170. instance, the following invocations are equivalent:
  2171. @example
  2172. guix build --log-file `guix build -d guile`
  2173. guix build --log-file `guix build guile`
  2174. guix build --log-file guile
  2175. guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
  2176. @end example
  2177. @end table
  2178. @cindex common build options
  2179. In addition, a number of options that control the build process are
  2180. common to @command{guix build} and other commands that can spawn builds,
  2181. such as @command{guix package} or @command{guix archive}. These are the
  2182. following:
  2183. @table @code
  2184. @item --load-path=@var{directory}
  2185. @itemx -L @var{directory}
  2186. Add @var{directory} to the front of the package module search path
  2187. (@pxref{Package Modules}).
  2188. This allows users to define their own packages and make them visible to
  2189. the command-line tools.
  2190. @item --keep-failed
  2191. @itemx -K
  2192. Keep the build tree of failed builds. Thus, if a build fail, its build
  2193. tree is kept under @file{/tmp}, in a directory whose name is shown at
  2194. the end of the build log. This is useful when debugging build issues.
  2195. @item --dry-run
  2196. @itemx -n
  2197. Do not build the derivations.
  2198. @item --fallback
  2199. When substituting a pre-built binary fails, fall back to building
  2200. packages locally.
  2201. @item --no-substitutes
  2202. Do not use substitutes for build products. That is, always build things
  2203. locally instead of allowing downloads of pre-built binaries
  2204. (@pxref{Substitutes}).
  2205. @item --no-build-hook
  2206. Do not attempt to offload builds @i{via} the daemon's ``build hook''
  2207. (@pxref{Daemon Offload Setup}). That is, always build things locally
  2208. instead of offloading builds to remote machines.
  2209. @item --max-silent-time=@var{seconds}
  2210. When the build or substitution process remains silent for more than
  2211. @var{seconds}, terminate it and report a build failure.
  2212. @item --timeout=@var{seconds}
  2213. Likewise, when the build or substitution process lasts for more than
  2214. @var{seconds}, terminate it and report a build failure.
  2215. By default there is no timeout. This behavior can be restored with
  2216. @code{--timeout=0}.
  2217. @item --verbosity=@var{level}
  2218. Use the given verbosity level. @var{level} must be an integer between 0
  2219. and 5; higher means more verbose output. Setting a level of 4 or more
  2220. may be helpful when debugging setup issues with the build daemon.
  2221. @item --cores=@var{n}
  2222. @itemx -c @var{n}
  2223. Allow the use of up to @var{n} CPU cores for the build. The special
  2224. value @code{0} means to use as many CPU cores as available.
  2225. @item --max-jobs=@var{n}
  2226. @itemx -M @var{n}
  2227. Allow at most @var{n} build jobs in parallel. @xref{Invoking
  2228. guix-daemon, @code{--max-jobs}}, for details about this option and the
  2229. equivalent @command{guix-daemon} option.
  2230. @end table
  2231. Behind the scenes, @command{guix build} is essentially an interface to
  2232. the @code{package-derivation} procedure of the @code{(guix packages)}
  2233. module, and to the @code{build-derivations} procedure of the @code{(guix
  2234. store)} module.
  2235. In addition to options explicitly passed on the command line,
  2236. @command{guix build} and other @command{guix} commands that support
  2237. building honor the @code{GUIX_BUILD_OPTIONS} environment variable.
  2238. @defvr {Environment Variable} GUIX_BUILD_OPTIONS
  2239. Users can define this variable to a list of command line options that
  2240. will automatically be used by @command{guix build} and other
  2241. @command{guix} commands that can perform builds, as in the example
  2242. below:
  2243. @example
  2244. $ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
  2245. @end example
  2246. These options are parsed independently, and the result is appended to
  2247. the parsed command-line options.
  2248. @end defvr
  2249. @node Invoking guix download
  2250. @section Invoking @command{guix download}
  2251. When writing a package definition, developers typically need to download
  2252. the package's source tarball, compute its SHA256 hash, and write that
  2253. hash in the package definition (@pxref{Defining Packages}). The
  2254. @command{guix download} tool helps with this task: it downloads a file
  2255. from the given URI, adds it to the store, and prints both its file name
  2256. in the store and its SHA256 hash.
  2257. The fact that the downloaded file is added to the store saves bandwidth:
  2258. when the developer eventually tries to build the newly defined package
  2259. with @command{guix build}, the source tarball will not have to be
  2260. downloaded again because it is already in the store. It is also a
  2261. convenient way to temporarily stash files, which may be deleted
  2262. eventually (@pxref{Invoking guix gc}).
  2263. The @command{guix download} command supports the same URIs as used in
  2264. package definitions. In particular, it supports @code{mirror://} URIs.
  2265. @code{https} URIs (HTTP over TLS) are supported @emph{provided} the
  2266. Guile bindings for GnuTLS are available in the user's environment; when
  2267. they are not available, an error is raised. @xref{Guile Preparations,
  2268. how to install the GnuTLS bindings for Guile,, gnutls-guile,
  2269. GnuTLS-Guile}, for more information.
  2270. The following option is available:
  2271. @table @code
  2272. @item --format=@var{fmt}
  2273. @itemx -f @var{fmt}
  2274. Write the hash in the format specified by @var{fmt}. For more
  2275. information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
  2276. @end table
  2277. @node Invoking guix hash
  2278. @section Invoking @command{guix hash}
  2279. The @command{guix hash} command computes the SHA256 hash of a file.
  2280. It is primarily a convenience tool for anyone contributing to the
  2281. distribution: it computes the cryptographic hash of a file, which can be
  2282. used in the definition of a package (@pxref{Defining Packages}).
  2283. The general syntax is:
  2284. @example
  2285. guix hash @var{option} @var{file}
  2286. @end example
  2287. @command{guix hash} has the following option:
  2288. @table @code
  2289. @item --format=@var{fmt}
  2290. @itemx -f @var{fmt}
  2291. Write the hash in the format specified by @var{fmt}.
  2292. Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
  2293. (@code{hex} and @code{hexadecimal} can be used as well).
  2294. If the @option{--format} option is not specified, @command{guix hash}
  2295. will output the hash in @code{nix-base32}. This representation is used
  2296. in the definitions of packages.
  2297. @item --recursive
  2298. @itemx -r
  2299. Compute the hash on @var{file} recursively.
  2300. In this case, the hash is computed on an archive containing @var{file},
  2301. including its children if it is a directory. Some of @var{file}'s
  2302. meta-data is part of the archive; for instance, when @var{file} is a
  2303. regular file, the hash is different depending on whether @var{file} is
  2304. executable or not. Meta-data such as time stamps has no impact on the
  2305. hash (@pxref{Invoking guix archive}).
  2306. @c FIXME: Replace xref above with xref to an ``Archive'' section when
  2307. @c it exists.
  2308. @end table
  2309. @node Invoking guix import
  2310. @section Invoking @command{guix import}
  2311. @cindex importing packages
  2312. @cindex package import
  2313. @cindex package conversion
  2314. The @command{guix import} command is useful for people willing to add a
  2315. package to the distribution but who'd rather do as little work as
  2316. possible to get there---a legitimate demand. The command knows of a few
  2317. repositories from which it can ``import'' package meta-data. The result
  2318. is a package definition, or a template thereof, in the format we know
  2319. (@pxref{Defining Packages}).
  2320. The general syntax is:
  2321. @example
  2322. guix import @var{importer} @var{options}@dots{}
  2323. @end example
  2324. @var{importer} specifies the source from which to import package
  2325. meta-data, and @var{options} specifies a package identifier and other
  2326. options specific to @var{importer}. Currently, the available
  2327. ``importers'' are:
  2328. @table @code
  2329. @item gnu
  2330. Import meta-data for the given GNU package. This provides a template
  2331. for the latest version of that GNU package, including the hash of its
  2332. source tarball, and its canonical synopsis and description.
  2333. Additional information such as the package's dependencies and its
  2334. license needs to be figured out manually.
  2335. For example, the following command returns a package definition for
  2336. GNU@tie{}Hello:
  2337. @example
  2338. guix import gnu hello
  2339. @end example
  2340. Specific command-line options are:
  2341. @table @code
  2342. @item --key-download=@var{policy}
  2343. As for @code{guix refresh}, specify the policy to handle missing OpenPGP
  2344. keys when verifying the package's signature. @xref{Invoking guix
  2345. refresh, @code{--key-download}}.
  2346. @end table
  2347. @item pypi
  2348. @cindex pypi
  2349. Import meta-data from the @uref{, Python Package
  2350. Index}@footnote{This functionality requires Guile-JSON to be installed.
  2351. @xref{Requirements}.}. Information is taken from the JSON-formatted
  2352. description available at @code{} and usually includes all
  2353. the relevant information, including package dependencies.
  2354. The command below imports meta-data for the @code{itsdangerous} Python
  2355. package:
  2356. @example
  2357. guix import pypi itsdangerous
  2358. @end example
  2359. @item nix
  2360. Import meta-data from a local copy of the source of the
  2361. @uref{, Nixpkgs distribution}@footnote{This
  2362. relies on the @command{nix-instantiate} command of
  2363. @uref{, Nix}.}. Package definitions in Nixpkgs are
  2364. typically written in a mixture of Nix-language and Bash code. This
  2365. command only imports the high-level package structure that is written in
  2366. the Nix language. It normally includes all the basic fields of a
  2367. package definition.
  2368. When importing a GNU package, the synopsis and descriptions are replaced
  2369. by their canonical upstream variant.
  2370. As an example, the command below imports the package definition of
  2371. LibreOffice (more precisely, it imports the definition of the package
  2372. bound to the @code{libreoffice} top-level attribute):
  2373. @example
  2374. guix import nix ~/path/to/nixpkgs libreoffice
  2375. @end example
  2376. @end table
  2377. The structure of the @command{guix import} code is modular. It would be
  2378. useful to have more importers for other package formats, and your help
  2379. is welcome here (@pxref{Contributing}).
  2380. @node Invoking guix refresh
  2381. @section Invoking @command{guix refresh}
  2382. The primary audience of the @command{guix refresh} command is developers
  2383. of the GNU software distribution. By default, it reports any packages
  2384. provided by the distribution that are outdated compared to the latest
  2385. upstream version, like this:
  2386. @example
  2387. $ guix refresh
  2388. gnu/packages/gettext.scm:29:13: gettext would be upgraded from to
  2389. gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
  2390. @end example
  2391. It does so by browsing each package's FTP directory and determining the
  2392. highest version number of the source tarballs
  2393. therein@footnote{Currently, this only works for GNU packages.}.
  2394. When passed @code{--update}, it modifies distribution source files to
  2395. update the version numbers and source tarball hashes of those packages'
  2396. recipes (@pxref{Defining Packages}). This is achieved by downloading
  2397. each package's latest source tarball and its associated OpenPGP
  2398. signature, authenticating the downloaded tarball against its signature
  2399. using @command{gpg}, and finally computing its hash. When the public
  2400. key used to sign the tarball is missing from the user's keyring, an
  2401. attempt is made to automatically retrieve it from a public key server;
  2402. when it's successful, the key is added to the user's keyring; otherwise,
  2403. @command{guix refresh} reports an error.
  2404. The following options are supported:
  2405. @table @code
  2406. @item --update
  2407. @itemx -u
  2408. Update distribution source files (package recipes) in place.
  2409. @xref{Defining Packages}, for more information on package definitions.
  2410. @item --select=[@var{subset}]
  2411. @itemx -s @var{subset}
  2412. Select all the packages in @var{subset}, one of @code{core} or
  2413. @code{non-core}.
  2414. The @code{core} subset refers to all the packages at the core of the
  2415. distribution---i.e., packages that are used to build ``everything
  2416. else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
  2417. changing one of these packages in the distribution entails a rebuild of
  2418. all the others. Thus, such updates are an inconvenience to users in
  2419. terms of build time or bandwidth used to achieve the upgrade.
  2420. The @code{non-core} subset refers to the remaining packages. It is
  2421. typically useful in cases where an update of the core packages would be
  2422. inconvenient.
  2423. @end table
  2424. In addition, @command{guix refresh} can be passed one or more package
  2425. names, as in this example:
  2426. @example
  2427. guix refresh -u emacs idutils
  2428. @end example
  2429. @noindent
  2430. The command above specifically updates the @code{emacs} and
  2431. @code{idutils} packages. The @code{--select} option would have no
  2432. effect in this case.
  2433. When considering whether to upgrade a package, it is sometimes
  2434. convenient to know which packages would be affected by the upgrade and
  2435. should be checked for compatibility. For this the following option may
  2436. be used when passing @command{guix refresh} one or more package names:
  2437. @table @code
  2438. @item --list-dependent
  2439. @itemx -l
  2440. List top-level dependent packages that would need to be rebuilt as a
  2441. result of upgrading one or more packages.
  2442. @end table
  2443. Be aware that the @code{--list-dependent} option only
  2444. @emph{approximates} the rebuilds that would be required as a result of
  2445. an upgrade. More rebuilds might be required under some circumstances.
  2446. @example
  2447. $ guix refresh --list-dependent flex
  2448. Building the following 120 packages would ensure 213 dependent packages are rebuilt:
  2449. hop-2.4.0 geiser-0.4 notmuch-0.18 mu- cflow-1.4 idutils-4.6 @dots{}
  2450. @end example
  2451. The command above lists a set of packages that could be built to check
  2452. for compatibility with an upgraded @code{flex} package.
  2453. The following options can be used to customize GnuPG operation:
  2454. @table @code
  2455. @item --gpg=@var{command}
  2456. Use @var{command} as the GnuPG 2.x command. @var{command} is searched
  2457. for in @code{$PATH}.
  2458. @item --key-download=@var{policy}
  2459. Handle missing OpenPGP keys according to @var{policy}, which may be one
  2460. of:
  2461. @table @code
  2462. @item always
  2463. Always download missing OpenPGP keys from the key server, and add them
  2464. to the user's GnuPG keyring.
  2465. @item never
  2466. Never try to download missing OpenPGP keys. Instead just bail out.
  2467. @item interactive
  2468. When a package signed with an unknown OpenPGP key is encountered, ask
  2469. the user whether to download it or not. This is the default behavior.
  2470. @end table
  2471. @item --key-server=@var{host}
  2472. Use @var{host} as the OpenPGP key server when importing a public key.
  2473. @end table
  2474. @node Invoking guix lint
  2475. @section Invoking @command{guix lint}
  2476. The @command{guix lint} is meant to help package developers avoid common
  2477. errors and use a consistent style. It runs a few checks on a given set of
  2478. packages in order to find common mistakes in their definitions.
  2479. The general syntax is:
  2480. @example
  2481. guix lint @var{options} @var{package}@dots{}
  2482. @end example
  2483. If no package is given on the command line, then all packages are checked.
  2484. The @var{options} may be zero or more of the following:
  2485. @table @code
  2486. @item --checkers
  2487. @itemx -c
  2488. Only enable the checkers specified in a comma-separated list using the
  2489. names returned by @code{--list-checkers}.
  2490. @item --list-checkers
  2491. @itemx -l
  2492. List and describe all the available checkers that will be run on packages
  2493. and exit.
  2494. @end table
  2495. @node Invoking guix environment
  2496. @section Invoking @command{guix environment}
  2497. @cindex reproducible build environments
  2498. The purpose of @command{guix environment} is to assist hackers in
  2499. creating reproducible development environments without polluting their
  2500. package profile. The @command{guix environment} tool takes one or more
  2501. packages, builds all of the necessary inputs, and creates a shell
  2502. environment to use them.
  2503. The general syntax is:
  2504. @example
  2505. guix environment @var{options} @var{package}@dots{}
  2506. @end example
  2507. The following examples spawns a new shell that is capable of building
  2508. the GNU Guile source code:
  2509. @example
  2510. guix environment guile
  2511. @end example
  2512. If the specified packages are not built yet, @command{guix environment}
  2513. automatically builds them. The new shell's environment is an augmented
  2514. version of the environment that @command{guix environment} was run in.
  2515. It contains the necessary search paths for building the given package
  2516. added to the existing environment variables. To create a ``pure''
  2517. environment in which the original environment variables have been unset,
  2518. use the @code{--pure} option.
  2519. Additionally, more than one package may be specified, in which case the
  2520. union of the inputs for the given packages are used. For example, the
  2521. command below spawns a shell where all of the dependencies of both Guile
  2522. and Emacs are available:
  2523. @example
  2524. guix environment guile emacs
  2525. @end example
  2526. Sometimes an interactive shell session is not desired. The
  2527. @code{--exec} option can be used to specify the command to run instead.
  2528. @example
  2529. guix environment guile --exec=make
  2530. @end example
  2531. The following options are available:
  2532. @table @code
  2533. @item --expression=@var{expr}
  2534. @itemx -e @var{expr}
  2535. Create an environment for the package that @var{expr} evaluates to.
  2536. @item --load=@var{file}
  2537. @itemx -l @var{file}
  2538. Create an environment for the package that the code within @var{file}
  2539. evaluates to.
  2540. @item --exec=@var{command}
  2541. @item -E @var{command}
  2542. Execute @var{command} in the new environment.
  2543. @item --pure
  2544. Unset existing environment variables when building the new environment.
  2545. This has the effect of creating an environment in which search paths
  2546. only contain package inputs.
  2547. @item --search-paths
  2548. Display the environment variable definitions that make up the
  2549. environment.
  2550. @end table
  2551. It also supports all of the common build options that @command{guix
  2552. build} supports (@pxref{Invoking guix build, common build options}).
  2553. @c *********************************************************************
  2554. @node GNU Distribution
  2555. @chapter GNU Distribution
  2556. Guix comes with a distribution of free software@footnote{The term
  2557. ``free'' here refers to the
  2558. @url{,freedom provided to
  2559. users of that software}.} that forms the basis of the GNU system. This
  2560. includes core GNU packages such as GNU libc, GCC, and Binutils, as well
  2561. as many GNU and non-GNU applications. The complete list of available
  2562. packages can be browsed
  2563. @url{,on-line} or by
  2564. running @command{guix package} (@pxref{Invoking guix package}):
  2565. @example
  2566. guix package --list-available
  2567. @end example
  2568. Our goal is to build a practical 100% free software distribution of
  2569. Linux-based and other variants of GNU, with a focus on the promotion and
  2570. tight integration of GNU components, and an emphasis on programs and
  2571. tools that help users exert that freedom.
  2572. The GNU distribution is currently available on the following platforms:
  2573. @table @code
  2574. @item x86_64-linux
  2575. Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
  2576. @item i686-linux
  2577. Intel 32-bit architecture (IA32), Linux-Libre kernel;
  2578. @item armhf-linux
  2579. ARMv7-A architecture with hard float, Thumb-2 and VFP3D16 coprocessor,
  2580. using the EABI hard-float ABI, and Linux-Libre kernel.
  2581. @item mips64el-linux
  2582. little-endian 64-bit MIPS processors, specifically the Loongson series,
  2583. n32 application binary interface (ABI), and Linux-Libre kernel.
  2584. @end table
  2585. @noindent
  2586. For information on porting to other architectures or kernels,
  2587. @xref{Porting}.
  2588. @menu
  2589. * System Installation:: Installing the whole operating system.
  2590. * System Configuration:: Configuring a GNU system.
  2591. * Installing Debugging Files:: Feeding the debugger.
  2592. * Security Updates:: Deploying security fixes quickly.
  2593. * Package Modules:: Packages from the programmer's viewpoint.
  2594. * Packaging Guidelines:: Growing the distribution.
  2595. * Bootstrapping:: GNU/Linux built from scratch.
  2596. * Porting:: Targeting another platform or kernel.
  2597. @end menu
  2598. Building this distribution is a cooperative effort, and you are invited
  2599. to join! @xref{Contributing}, for information about how you can help.
  2600. @node System Installation
  2601. @section System Installation
  2602. This section explains how to install the complete GNU operating system
  2603. on a machine. The Guix package manager can also be installed on top of
  2604. a running GNU/Linux system, @pxref{Installation}.
  2605. @ifinfo
  2606. @c This paragraph is for people reading this from tty2 of the
  2607. @c installation image.
  2608. You're reading this documentation with an Info reader. For details on
  2609. how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
  2610. link that follows: @pxref{Help,,, info, Info: An Introduction}. Hit
  2611. @kbd{l} afterwards to come back here.
  2612. @end ifinfo
  2613. @subsection Limitations
  2614. As of version @value{VERSION}, GNU@tie{}Guix and the GNU system
  2615. distribution are alpha software. It may contain bugs and lack important
  2616. features. Thus, if you are looking for a stable production system that
  2617. respects your freedom as a computer user, a good solution at this point
  2618. is to consider @url{, one of
  2619. more established GNU/Linux distributions}. We hope you can soon switch
  2620. to the GNU system without fear, of course. In the meantime, you can
  2621. also keep using your distribution and try out the package manager on top
  2622. of it (@pxref{Installation}).
  2623. Before you proceed with the installation, be aware of the following
  2624. noteworthy limitations applicable to version @value{VERSION}:
  2625. @itemize
  2626. @item
  2627. The installation process does not include a graphical user interface and
  2628. requires familiarity with GNU/Linux (see the following subsections to
  2629. get a feel of what that means.)
  2630. @item
  2631. The system does not yet provide graphical desktop environments such as
  2632. GNOME and KDE.
  2633. @item
  2634. Support for the Logical Volume Manager (LVM) is missing.
  2635. @item
  2636. Few system services are currently supported out-of-the-box
  2637. (@pxref{Services}).
  2638. @item
  2639. On the order of 1,000 packages are available, which means that you may
  2640. occasionally find that a useful package is missing.
  2641. @end itemize
  2642. You've been warned. But more than a disclaimer, this is an invitation
  2643. to report issues (and success stories!), and join us in improving it.
  2644. @xref{Contributing}, for more info.
  2645. @subsection USB Stick Installation
  2646. An installation image for USB sticks can be downloaded from
  2647. @url{{VERSION}.@var{system}.xz},
  2648. where @var{system} is one of:
  2649. @table @code
  2650. @item x86_64-linux
  2651. for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
  2652. @item i686-linux
  2653. for a 32-bit GNU/Linux system on Intel-compatible CPUs.
  2654. @end table
  2655. This image contains a single partition with the tools necessary for an
  2656. installation. It is meant to be copied @emph{as is} to a large-enough
  2657. USB stick.
  2658. To copy the image to a USB stick, follow these steps:
  2659. @enumerate
  2660. @item
  2661. Decompress the image using the @command{xz} command:
  2662. @example
  2663. xz -d gnu-usb-install-@value{VERSION}.@var{system}.xz
  2664. @end example
  2665. @item
  2666. Insert a USB stick of 1@tie{}GiB or more in your machine, and determine
  2667. its device name. Assuming that USB stick is known as @file{/dev/sdX},
  2668. copy the image with:
  2669. @example
  2670. dd if=gnu-usb-install-@value{VERSION}.x86_64 of=/dev/sdX
  2671. @end example
  2672. Access to @file{/dev/sdX} usually requires root privileges.
  2673. @end enumerate
  2674. Once this is done, you should be able to reboot the system and boot from
  2675. the USB stick. The latter usually requires you to get in the BIOS' boot
  2676. menu, where you can choose to boot from the USB stick.
  2677. @subsection Preparing for Installation
  2678. Once you have successfully booted the image on the USB stick, you should
  2679. end up with a root prompt. Several console TTYs are configured and can
  2680. be used to run commands as root. TTY2 shows this documentation,
  2681. browsable using the Info reader commands (@pxref{Help,,, info, Info: An
  2682. Introduction}).
  2683. To install the system, you would:
  2684. @enumerate
  2685. @item
  2686. Configure the network, by running @command{dhclient eth0} (to get an
  2687. automatically assigned IP address from the wired network interface
  2688. controller), or using the @command{ifconfig} command.
  2689. The system automatically loads drivers for your network interface
  2690. controllers.
  2691. Setting up network access is almost always a requirement because the
  2692. image does not contain all the software and tools that may be needed.
  2693. @item
  2694. Unless this has already been done, you must partition and format the
  2695. target partitions.
  2696. Preferably, assign partitions a label so that you can easily and
  2697. reliably refer to them in @code{file-system} declarations (@pxref{File
  2698. Systems}). This is typically done using the @code{-L} option of
  2699. @command{mkfs.ext4} and related commands.
  2700. The installation image includes Parted (@pxref{Overview,,, parted, GNU
  2701. Parted User Manual}), @command{fdisk}, Cryptsetup/LUKS for disk
  2702. encryption, and e2fsprogs, the suite of tools to manipulate
  2703. ext2/ext3/ext4 file systems.
  2704. @item
  2705. Once that is done, mount the target root partition under @file{/mnt}.
  2706. @item
  2707. Lastly, run @code{deco start cow-store /mnt}.
  2708. This will make @file{/gnu/store} copy-on-write, such that packages added
  2709. to it during the installation phase will be written to the target disk
  2710. rather than kept in memory.
  2711. @end enumerate
  2712. @subsection Proceeding with the Installation
  2713. With the target partitions ready, you now have to edit a file and
  2714. provide the declaration of the operating system to be installed. To
  2715. that end, the installation system comes with two text editors: GNU nano
  2716. (@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone.
  2717. It is better to store that file on the target root file system, say, as
  2718. @file{/mnt/etc/config.scm}.
  2719. A minimal operating system configuration, with just the bare minimum and
  2720. only a root account would look like this (on the installation system,
  2721. this example is available as @file{/etc/configuration-template.scm}):
  2722. @example
  2723. @include os-config.texi
  2724. @end example
  2725. @noindent
  2726. For more information on @code{operating-system} declarations,
  2727. @pxref{Using the Configuration System}.
  2728. Once that is done, the new system must be initialized (remember that the
  2729. target root file system is mounted under @file{/mnt}):
  2730. @example
  2731. guix system init /mnt/etc/config.scm /mnt
  2732. @end example
  2733. @noindent
  2734. This will copy all the necessary files, and install GRUB on
  2735. @file{/dev/sdX}, unless you pass the @option{--no-grub} option. For
  2736. more information, @pxref{Invoking guix system}. This command may trigger
  2737. downloads or builds of missing packages, which can take some time.
  2738. Once that command has completed---and hopefully succeeded!---you can
  2739. run @command{reboot} and boot into the new system. Cross fingers, and
  2740. join us on @code{#guix} on the Freenode IRC network or on
  2741. @file{} to share your experience---good or not so
  2742. good.
  2743. @subsection Building the Installation Image
  2744. The installation image described above was built using the @command{guix
  2745. system} command, specifically:
  2746. @example
  2747. guix system disk-image --image-size=800MiB gnu/system/install.scm
  2748. @end example
  2749. @xref{Invoking guix system}, for more information. See
  2750. @file{gnu/system/install.scm} in the source tree for more information
  2751. about the installation image.
  2752. @node System Configuration
  2753. @section System Configuration
  2754. @cindex system configuration
  2755. The GNU system supports a consistent whole-system configuration
  2756. mechanism. By that we mean that all aspects of the global system
  2757. configuration---such as the available system services, timezone and
  2758. locale settings, user accounts---are declared in a single place. Such
  2759. a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
  2760. One of the advantages of putting all the system configuration under the
  2761. control of Guix is that it supports transactional system upgrades, and
  2762. makes it possible to roll-back to a previous system instantiation,
  2763. should something go wrong with the new one (@pxref{Features}). Another
  2764. one is that it makes it easy to replicate the exact same configuration
  2765. across different machines, or at different points in time, without
  2766. having to resort to additional administration tools layered on top of
  2767. the system's own tools.
  2768. @c Yes, we're talking of Puppet, Chef, & co. here. ↑
  2769. This section describes this mechanism. First we focus on the system
  2770. administrator's viewpoint---explaining how the system is configured and
  2771. instantiated. Then we show how this mechanism can be extended, for
  2772. instance to support new system services.
  2773. @menu
  2774. * Using the Configuration System:: Customizing your GNU system.
  2775. * operating-system Reference:: Detail of operating-system declarations.
  2776. * File Systems:: Configuring file system mounts.
  2777. * Mapped Devices:: Block device extra processing.
  2778. * User Accounts:: Specifying user accounts.
  2779. * Locales:: Language and cultural convention settings.
  2780. * Services:: Specifying system services.
  2781. * Setuid Programs:: Programs running with root privileges.
  2782. * Initial RAM Disk:: Linux-Libre bootstrapping.
  2783. * GRUB Configuration:: Configuring the boot loader.
  2784. * Invoking guix system:: Instantiating a system configuration.
  2785. * Defining Services:: Adding new service definitions.
  2786. @end menu
  2787. @node Using the Configuration System
  2788. @subsection Using the Configuration System
  2789. The operating system is configured by providing an
  2790. @code{operating-system} declaration in a file that can then be passed to
  2791. the @command{guix system} command (@pxref{Invoking guix system}). A
  2792. simple setup, with the default system services, the default Linux-Libre
  2793. kernel, initial RAM disk, and boot loader looks like this:
  2794. @findex operating-system
  2795. @lisp
  2796. (use-modules (gnu) ; for 'user-account', '%base-services', etc.
  2797. (gnu packages emacs) ; for 'emacs'
  2798. (gnu services ssh)) ; for 'lsh-service'
  2799. (operating-system
  2800. (host-name "komputilo")
  2801. (timezone "Europe/Paris")
  2802. (locale "fr_FR.utf8")
  2803. (bootloader (grub-configuration
  2804. (device "/dev/sda")))
  2805. (file-systems (cons (file-system
  2806. (device "/dev/sda1") ; or partition label
  2807. (mount-point "/")
  2808. (type "ext3"))
  2809. %base-file-systems))
  2810. (users (list (user-account
  2811. (name "alice")
  2812. (group "users")
  2813. (comment "Bob's sister")
  2814. (home-directory "/home/alice"))))
  2815. (packages (cons emacs %base-packages))
  2816. (services (cons (lsh-service #:port 2222 #:root-login? #t)
  2817. %base-services)))
  2818. @end lisp
  2819. This example should be self-describing. Some of the fields defined
  2820. above, such as @code{host-name} and @code{bootloader}, are mandatory.
  2821. Others, such as @code{packages} and @code{services}, can be omitted, in
  2822. which case they get a default value.
  2823. @vindex %base-packages
  2824. The @code{packages} field lists
  2825. packages that will be globally visible on the system, for all user
  2826. accounts---i.e., in every user's @code{PATH} environment variable---in
  2827. addition to the per-user profiles (@pxref{Invoking guix package}). The
  2828. @var{%base-packages} variable provides all the tools one would expect
  2829. for basic user and administrator tasks---including the GNU Core
  2830. Utilities, the GNU Networking Utilities, the GNU Zile lightweight text
  2831. editor, @command{find}, @command{grep}, etc. The example above adds
  2832. Emacs to those, taken from the @code{(gnu packages emacs)} module
  2833. (@pxref{Package Modules}).
  2834. @vindex %base-services
  2835. The @code{services} field lists @dfn{system services} to be made
  2836. available when the system starts (@pxref{Services}).
  2837. The @code{operating-system} declaration above specifies that, in
  2838. addition to the basic services, we want the @command{lshd} secure shell
  2839. daemon listening on port 2222, and allowing remote @code{root} logins
  2840. (@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood,
  2841. @code{lsh-service} arranges so that @code{lshd} is started with the
  2842. right command-line options, possibly with supporting configuration files
  2843. generated as needed (@pxref{Defining Services}). @xref{operating-system
  2844. Reference}, for details about the available @code{operating-system}
  2845. fields.
  2846. Assuming the above snippet is stored in the @file{my-system-config.scm}
  2847. file, the @command{guix system reconfigure my-system-config.scm} command
  2848. instantiates that configuration, and makes it the default GRUB boot
  2849. entry (@pxref{Invoking guix system}). The normal way to change the
  2850. system's configuration is by updating this file and re-running the
  2851. @command{guix system} command.
  2852. At the Scheme level, the bulk of an @code{operating-system} declaration
  2853. is instantiated with the following monadic procedure (@pxref{The Store
  2854. Monad}):
  2855. @deffn {Monadic Procedure} operating-system-derivation os
  2856. Return a derivation that builds @var{os}, an @code{operating-system}
  2857. object (@pxref{Derivations}).
  2858. The output of the derivation is a single directory that refers to all
  2859. the packages, configuration files, and other supporting files needed to
  2860. instantiate @var{os}.
  2861. @end deffn
  2862. @node operating-system Reference
  2863. @subsection @code{operating-system} Reference
  2864. This section summarizes all the options available in
  2865. @code{operating-system} declarations (@pxref{Using the Configuration
  2866. System}).
  2867. @deftp {Data Type} operating-system
  2868. This is the data type representing an operating system configuration.
  2869. By that, we mean all the global system configuration, not per-user
  2870. configuration (@pxref{Using the Configuration System}).
  2871. @table @asis
  2872. @item @code{kernel} (default: @var{linux-libre})
  2873. The package object of the operating system to use@footnote{Currently
  2874. only the Linux-libre kernel is supported. In the future, it will be
  2875. possible to use the GNU@tie{}Hurd.}.
  2876. @item @code{bootloader}
  2877. The system bootloader configuration object. @xref{GRUB Configuration}.
  2878. @item @code{initrd} (default: @code{base-initrd})
  2879. A two-argument monadic procedure that returns an initial RAM disk for
  2880. the Linux kernel. @xref{Initial RAM Disk}.
  2881. @item @code{firmware} (default: @var{%base-firmware})
  2882. @cindex firmware
  2883. List of firmware packages loadable by the operating system kernel.
  2884. The default includes firmware needed for Atheros-based WiFi devices
  2885. (Linux-libre module @code{ath9k}.)
  2886. @item @code{host-name}
  2887. The host name.
  2888. @item @code{hosts-file}
  2889. @cindex hosts file
  2890. A zero-argument monadic procedure that returns a text file for use as
  2891. @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
  2892. Reference Manual}). The default is to produce a file with entries for
  2893. @code{localhost} and @var{host-name}.
  2894. @item @code{mapped-devices} (default: @code{'()})
  2895. A list of mapped devices. @xref{Mapped Devices}.
  2896. @item @code{file-systems}
  2897. A list of file systems. @xref{File Systems}.
  2898. @item @code{swap-devices} (default: @code{'()})
  2899. @cindex swap devices
  2900. A list of strings identifying devices to be used for ``swap space''
  2901. (@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}).
  2902. For example, @code{'("/dev/sda3")}.
  2903. @item @code{users} (default: @code{'()})
  2904. @itemx @code{groups} (default: @var{%base-groups})
  2905. List of user accounts and groups. @xref{User Accounts}.
  2906. @item @code{skeletons} (default: @code{(default-skeletons)})
  2907. A monadic list of pairs of target file name and files. These are the
  2908. files that will be used as skeletons as new accounts are created.
  2909. For instance, a valid value may look like this:
  2910. @example
  2911. (mlet %store-monad ((bashrc (text-file "bashrc" "\
  2912. export PATH=$HOME/.guix-profile/bin")))
  2913. (return `((".bashrc" ,bashrc))))
  2914. @end example
  2915. @item @code{issue} (default: @var{%default-issue})
  2916. A string denoting the contents of the @file{/etc/issue} file, which is
  2917. what displayed when users log in on a text console.
  2918. @item @code{packages} (default: @var{%base-packages})
  2919. The set of packages installed in the global profile, which is accessible
  2920. at @file{/run/current-system/profile}.
  2921. The default set includes core utilities, but it is good practice to
  2922. install non-core utilities in user profiles (@pxref{Invoking guix
  2923. package}).
  2924. @item @code{timezone}
  2925. A timezone identifying string---e.g., @code{"Europe/Paris"}.
  2926. @item @code{locale} (default: @code{"en_US.utf8"})
  2927. The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
  2928. Library Reference Manual}). @xref{Locales}, for more information.
  2929. @item @code{locale-definitions} (default: @var{%default-locale-definitions})
  2930. The list of locale definitions to be compiled and that may be used at
  2931. run time. @xref{Locales}.
  2932. @item @code{services} (default: @var{%base-services})
  2933. A list of monadic values denoting system services. @xref{Services}.
  2934. @item @code{pam-services} (default: @code{(base-pam-services)})
  2935. @cindex PAM
  2936. @cindex pluggable authentication modules
  2937. Linux @dfn{pluggable authentication module} (PAM) services.
  2938. @c FIXME: Add xref to PAM services section.
  2939. @item @code{setuid-programs} (default: @var{%setuid-programs})
  2940. List of string-valued G-expressions denoting setuid programs.
  2941. @xref{Setuid Programs}.
  2942. @item @code{sudoers} (default: @var{%sudoers-specification})
  2943. @cindex sudoers
  2944. The contents of the @file{/etc/sudoers} file as a string.
  2945. This file specifies which users can use the @command{sudo} command, what
  2946. they are allowed to do, and what privileges they may gain. The default
  2947. is that only @code{root} and members of the @code{wheel} group may use
  2948. @code{sudo}.
  2949. @end table
  2950. @end deftp
  2951. @node File Systems
  2952. @subsection File Systems
  2953. The list of file systems to be mounted is specified in the
  2954. @code{file-systems} field of the operating system's declaration
  2955. (@pxref{Using the Configuration System}). Each file system is declared
  2956. using the @code{file-system} form, like this:
  2957. @example
  2958. (file-system
  2959. (mount-point "/home")
  2960. (device "/dev/sda3")
  2961. (type "ext4"))
  2962. @end example
  2963. As usual, some of the fields are mandatory---those shown in the example
  2964. above---while others can be omitted. These are described below.
  2965. @deftp {Data Type} file-system
  2966. Objects of this type represent file systems to be mounted. They
  2967. contain the following members:
  2968. @table @asis
  2969. @item @code{type}
  2970. This is a string specifying the type of the file system---e.g.,
  2971. @code{"ext4"}.
  2972. @item @code{mount-point}
  2973. This designates the place where the file system is to be mounted.
  2974. @item @code{device}
  2975. This names the ``source'' of the file system. By default it is the name
  2976. of a node under @file{/dev}, but its meaning depends on the @code{title}
  2977. field described below.
  2978. @item @code{title} (default: @code{'device})
  2979. This is a symbol that specifies how the @code{device} field is to be
  2980. interpreted.
  2981. When it is the symbol @code{device}, then the @code{device} field is
  2982. interpreted as a file name; when it is @code{label}, then @code{device}
  2983. is interpreted as a partition label name; when it is @code{uuid},
  2984. @code{device} is interpreted as a partition unique identifier (UUID).
  2985. The @code{label} and @code{uuid} options offer a way to refer to disk
  2986. partitions without having to hard-code their actual device name.
  2987. However, when a file system's source is a mapped device (@pxref{Mapped
  2988. Devices}), its @code{device} field @emph{must} refer to the mapped
  2989. device name---e.g., @file{/dev/mapper/root-partition}---and consequently
  2990. @code{title} must be set to @code{'device}. This is required so that
  2991. the system knows that mounting the file system depends on having the
  2992. corresponding device mapping established.
  2993. @item @code{flags} (default: @code{'()})
  2994. This is a list of symbols denoting mount flags. Recognized flags
  2995. include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
  2996. access to special files), @code{no-suid} (ignore setuid and setgid
  2997. bits), and @code{no-exec} (disallow program execution.)
  2998. @item @code{options} (default: @code{#f})
  2999. This is either @code{#f}, or a string denoting mount options.
  3000. @item @code{needed-for-boot?} (default: @code{#f})
  3001. This Boolean value indicates whether the file system is needed when
  3002. booting. If that is true, then the file system is mounted when the
  3003. initial RAM disk (initrd) is loaded. This is always the case, for
  3004. instance, for the root file system.
  3005. @item @code{check?} (default: @code{#t})
  3006. This Boolean indicates whether the file system needs to be checked for
  3007. errors before being mounted.
  3008. @item @code{create-mount-point?} (default: @code{#f})
  3009. When true, the mount point is created if it does not exist yet.
  3010. @end table
  3011. @end deftp
  3012. The @code{(gnu system file-systems)} exports the following useful
  3013. variables.
  3014. @defvr {Scheme Variable} %base-file-systems
  3015. These are essential file systems that are required on normal systems,
  3016. such as @var{%devtmpfs-file-system} (see below.) Operating system
  3017. declarations should always contain at least these.
  3018. @end defvr
  3019. @defvr {Scheme Variable} %devtmpfs-file-system
  3020. The @code{devtmpfs} file system to be mounted on @file{/dev}. This is a
  3021. requirement for udev (@pxref{Base Services, @code{udev-service}}).
  3022. @end defvr
  3023. @defvr {Scheme Variable} %pseudo-terminal-file-system
  3024. This is the file system to be mounted as @file{/dev/pts}. It supports
  3025. @dfn{pseudo-terminals} created @i{via} @code{openpty} and similar
  3026. functions (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference
  3027. Manual}). Pseudo-terminals are used by terminal emulators such as
  3028. @command{xterm}.
  3029. @end defvr
  3030. @defvr {Scheme Variable} %shared-memory-file-system
  3031. This file system is mounted as @file{/dev/shm} and is used to support
  3032. memory sharing across processes (@pxref{Memory-mapped I/O,
  3033. @code{shm_open},, libc, The GNU C Library Reference Manual}).
  3034. @end defvr
  3035. @defvr {Scheme Variable} %binary-format-file-system
  3036. The @code{binfmt_misc} file system, which allows handling of arbitrary
  3037. executable file types to be delegated to user space. This requires the
  3038. @code{binfmt.ko} kernel module to be loaded.
  3039. @end defvr
  3040. @defvr {Scheme Variable} %fuse-control-file-system
  3041. The @code{fusectl} file system, which allows unprivileged users to mount
  3042. and unmount user-space FUSE file systems. This requires the
  3043. @code{fuse.ko} kernel module to be loaded.
  3044. @end defvr
  3045. @node Mapped Devices
  3046. @subsection Mapped Devices
  3047. @cindex device mapping
  3048. @cindex mapped devices
  3049. The Linux kernel has a notion of @dfn{device mapping}: a block device,
  3050. such as a hard disk partition, can be @dfn{mapped} into another device,
  3051. with additional processing over the data that flows through
  3052. it@footnote{Note that the GNU@tie{}Hurd makes no difference between the
  3053. concept of a ``mapped device'' and that of a file system: both boil down
  3054. to @emph{translating} input/output operations made on a file to
  3055. operations on its backing store. Thus, the Hurd implements mapped
  3056. devices, like file systems, using the generic @dfn{translator} mechanism
  3057. (@pxref{Translators,,, hurd, The GNU Hurd Reference Manual}).}. A
  3058. typical example is encryption device mapping: all writes to the mapped
  3059. device are encrypted, and all reads are deciphered, transparently.
  3060. Mapped devices are declared using the @code{mapped-device} form:
  3061. @example
  3062. (mapped-device
  3063. (source "/dev/sda3")
  3064. (target "home")
  3065. (type luks-device-mapping))
  3066. @end example
  3067. @noindent
  3068. @cindex disk encryption
  3069. @cindex LUKS
  3070. This example specifies a mapping from @file{/dev/sda3} to
  3071. @file{/dev/mapper/home} using LUKS---the
  3072. @url{,Linux Unified Key Setup}, a
  3073. standard mechanism for disk encryption. The @file{/dev/mapper/home}
  3074. device can then be used as the @code{device} of a @code{file-system}
  3075. declaration (@pxref{File Systems}). The @code{mapped-device} form is
  3076. detailed below.
  3077. @deftp {Data Type} mapped-device
  3078. Objects of this type represent device mappings that will be made when
  3079. the system boots up.
  3080. @table @code
  3081. @item source
  3082. This string specifies the name of the block device to be mapped, such as
  3083. @code{"/dev/sda3"}.
  3084. @item target
  3085. This string specifies the name of the mapping to be established. For
  3086. example, specifying @code{"my-partition"} will lead to the creation of
  3087. the @code{"/dev/mapper/my-partition"} device.
  3088. @item type
  3089. This must be a @code{mapped-device-kind} object, which specifies how
  3090. @var{source} is mapped to @var{target}.
  3091. @end table
  3092. @end deftp
  3093. @defvr {Scheme Variable} luks-device-mapping
  3094. This defines LUKS block device encryption using the @command{cryptsetup}
  3095. command, from the same-named package. This relies on the
  3096. @code{dm-crypt} Linux kernel module.
  3097. @end defvr
  3098. @node User Accounts
  3099. @subsection User Accounts
  3100. User accounts are specified with the @code{user-account} form:
  3101. @example
  3102. (user-account
  3103. (name "alice")
  3104. (group "users")
  3105. (supplementary-groups '("wheel" ;allow use of sudo, etc.
  3106. "audio" ;sound card
  3107. "video" ;video devices such as webcams
  3108. "cdrom")) ;the good ol' CD-ROM
  3109. (comment "Bob's sister")
  3110. (home-directory "/home/alice"))
  3111. @end example
  3112. @deftp {Data Type} user-account
  3113. Objects of this type represent user accounts. The following members may
  3114. be specified:
  3115. @table @asis
  3116. @item @code{name}
  3117. The name of the user account.
  3118. @item @code{group}
  3119. This is the name (a string) or identifier (a number) of the user group
  3120. this account belongs to.
  3121. @item @code{supplementary-groups} (default: @code{'()})
  3122. Optionally, this can be defined as a list of group names that this
  3123. account belongs to.
  3124. @item @code{uid} (default: @code{#f})
  3125. This is the user ID for this account (a number), or @code{#f}. In the
  3126. latter case, a number is automatically chosen by the system when the
  3127. account is created.
  3128. @item @code{comment} (default: @code{""})
  3129. A comment about the account, such as the account's owner full name.
  3130. @item @code{home-directory}
  3131. This is the name of the home directory for the account.
  3132. @item @code{shell} (default: Bash)
  3133. This is a G-expression denoting the file name of a program to be used as
  3134. the shell (@pxref{G-Expressions}).
  3135. @item @code{system?} (default: @code{#f})
  3136. This Boolean value indicates whether the account is a ``system''
  3137. account. System accounts are sometimes treated specially; for instance,
  3138. graphical login managers do not list them.
  3139. @item @code{password} (default: @code{#f})
  3140. You would normally leave this field to @code{#f}, initialize user
  3141. passwords as @code{root} with the @command{passwd} command, and then let
  3142. users change it with @command{passwd}.
  3143. If you @emph{do} want to have a preset password for an account, then
  3144. this field must contain the encrypted password, as a string.
  3145. @xref{crypt,,, libc, The GNU C Library Reference Manual}, for more information
  3146. on password encryption, and @ref{Encryption,,, guile, GNU Guile Reference
  3147. Manual}, for information on Guile's @code{crypt} procedure.
  3148. @end table
  3149. @end deftp
  3150. User group declarations are even simpler:
  3151. @example
  3152. (user-group (name "students"))
  3153. @end example
  3154. @deftp {Data Type} user-group
  3155. This type is for, well, user groups. There are just a few fields:
  3156. @table @asis
  3157. @item @code{name}
  3158. The group's name.
  3159. @item @code{id} (default: @code{#f})
  3160. The group identifier (a number). If @code{#f}, a new number is
  3161. automatically allocated when the group is created.
  3162. @item @code{system?} (default: @code{#f})
  3163. This Boolean value indicates whether the group is a ``system'' group.
  3164. System groups have low numerical IDs.
  3165. @item @code{password} (default: @code{#f})
  3166. What, user groups can have a password? Well, apparently yes. Unless
  3167. @code{#f}, this field specifies the group's password.
  3168. @end table
  3169. @end deftp
  3170. For convenience, a variable lists all the basic user groups one may
  3171. expect:
  3172. @defvr {Scheme Variable} %base-groups
  3173. This is the list of basic user groups that users and/or packages expect
  3174. to be present on the system. This includes groups such as ``root'',
  3175. ``wheel'', and ``users'', as well as groups used to control access to
  3176. specific devices such as ``audio'', ``disk'', and ``cdrom''.
  3177. @end defvr
  3178. @node Locales
  3179. @subsection Locales
  3180. @cindex locale
  3181. A @dfn{locale} defines cultural conventions for a particular language
  3182. and region of the world (@pxref{Locales,,, libc, The GNU C Library
  3183. Reference Manual}). Each locale has a name that typically has the form
  3184. @code{@var{language}_@var{territory}.@var{charset}}---e.g.,
  3185. @code{fr_LU.utf8} designates the locale for the French language, with
  3186. cultural conventions from Luxembourg, and using the UTF-8 encoding.
  3187. @cindex locale definition
  3188. Usually, you will want to specify the default locale for the machine
  3189. using the @code{locale} field of the @code{operating-system} declaration
  3190. (@pxref{operating-system Reference, @code{locale}}).
  3191. That locale must be among the @dfn{locale definitions} that are known to
  3192. the system---and these are specified in the @code{locale-definitions}
  3193. slot of @code{operating-system}. The default value includes locale
  3194. definition for some widely used locales, but not for all the available
  3195. locales, in order to save space.
  3196. If the locale specified in the @code{locale} field is not among the
  3197. definitions listed in @code{locale-definitions}, @command{guix system}
  3198. raises an error. In that case, you should add the locale definition to
  3199. the @code{locale-definitions} field. For instance, to add the North
  3200. Frisian locale for Germany, the value of that field may be:
  3201. @example
  3202. (cons (locale-definition
  3203. (name "fy_DE.utf8") (source "fy_DE"))
  3204. %default-locale-definitions)
  3205. @end example
  3206. Likewise, to save space, one might want @code{locale-definitions} to
  3207. list only the locales that are actually used, as in:
  3208. @example
  3209. (list (locale-definition
  3210. (name "ja_JP.eucjp") (source "ja_JP")
  3211. (charset "EUC-JP")))
  3212. @end example
  3213. The @code{locale-definition} form is provided by the @code{(gnu system
  3214. locale)} module. Details are given below.
  3215. @deftp {Data Type} locale-definition
  3216. This is the data type of a locale definition.
  3217. @table @asis
  3218. @item @code{name}
  3219. The name of the locale. @xref{Locale Names,,, libc, The GNU C Library
  3220. Reference Manual}, for more information on locale names.
  3221. @item @code{source}
  3222. The name of the source for that locale. This is typically the
  3223. @code{@var{language}_@var{territory}} part of the locale name.
  3224. @item @code{charset} (default: @code{"UTF-8"})
  3225. The ``character set'' or ``code set'' for that locale,
  3226. @uref{, as defined by
  3227. IANA}.
  3228. @end table
  3229. @end deftp
  3230. @defvr {Scheme Variable} %default-locale-definitions
  3231. An arbitrary list of commonly used locales, used as the default value of
  3232. the @code{locale-definitions} field of @code{operating-system}
  3233. declarations.
  3234. @end defvr
  3235. @node Services
  3236. @subsection Services
  3237. @cindex system services
  3238. An important part of preparing an @code{operating-system} declaration is
  3239. listing @dfn{system services} and their configuration (@pxref{Using the
  3240. Configuration System}). System services are typically daemons launched
  3241. when the system boots, or other actions needed at that time---e.g.,
  3242. configuring network access.
  3243. Services are managed by GNU@tie{}dmd (@pxref{Introduction,,, dmd, GNU
  3244. dmd Manual}). On a running system, the @command{deco} command allows
  3245. you to list the available services, show their status, start and stop
  3246. them, or do other specific operations (@pxref{Jump Start,,, dmd, GNU dmd
  3247. Manual}). For example:
  3248. @example
  3249. # deco status dmd
  3250. @end example
  3251. The above command, run as @code{root}, lists the currently defined
  3252. services. The @command{deco doc} command shows a synopsis of the given
  3253. service:
  3254. @example
  3255. # deco doc nscd
  3256. Run libc's name service cache daemon (nscd).
  3257. @end example
  3258. The @command{start}, @command{stop}, and @command{restart} sub-commands
  3259. have the effect you would expect. For instance, the commands below stop
  3260. the nscd service and restart the Xorg display server:
  3261. @example
  3262. # deco stop nscd
  3263. Service nscd has been stopped.
  3264. # deco restart xorg-server
  3265. Service xorg-server has been stopped.
  3266. Service xorg-server has been started.
  3267. @end example
  3268. The following sections document the available services, starting with
  3269. the core services, that may be used in an @code{operating-system}
  3270. declaration.
  3271. @menu
  3272. * Base Services:: Essential system services.
  3273. * Networking Services:: Network setup, SSH daemon, etc.
  3274. * X Window:: Graphical display.
  3275. @end menu
  3276. @node Base Services
  3277. @subsubsection Base Services
  3278. The @code{(gnu services base)} module provides definitions for the basic
  3279. services that one expects from the system. The services exported by
  3280. this module are listed below.
  3281. @defvr {Scheme Variable} %base-services
  3282. This variable contains a list of basic services@footnote{Technically,
  3283. this is a list of monadic services. @xref{The Store Monad}.} one would
  3284. expect from the system: a login service (mingetty) on each tty, syslogd,
  3285. libc's name service cache daemon (nscd), the udev device manager, and
  3286. more.
  3287. This is the default value of the @code{services} field of
  3288. @code{operating-system} declarations. Usually, when customizing a
  3289. system, you will want to append services to @var{%base-services}, like
  3290. this:
  3291. @example
  3292. (cons* (avahi-service) (lsh-service) %base-services)
  3293. @end example
  3294. @end defvr
  3295. @deffn {Monadic Procedure} host-name-service @var{name}
  3296. Return a service that sets the host name to @var{name}.
  3297. @end deffn
  3298. @deffn {Monadic Procedure} mingetty-service @var{tty} [#:motd] @
  3299. [#:auto-login #f] [#:login-program] [#:login-pause? #f] @
  3300. [#:allow-empty-passwords? #f]
  3301. Return a service to run mingetty on @var{tty}.
  3302. When @var{allow-empty-passwords?} is true, allow empty log-in password. When
  3303. @var{auto-login} is true, it must be a user name under which to log-in
  3304. automatically. @var{login-pause?} can be set to @code{#t} in conjunction with
  3305. @var{auto-login}, in which case the user will have to press a key before the
  3306. login shell is launched.
  3307. When true, @var{login-program} is a gexp or a monadic gexp denoting the name
  3308. of the log-in program (the default is the @code{login} program from the Shadow
  3309. tool suite.)
  3310. @var{motd} is a monadic value containing a text file to use as
  3311. the ``message of the day''.
  3312. @end deffn
  3313. @cindex name service cache daemon
  3314. @cindex nscd
  3315. @deffn {Monadic Procedure} nscd-service [@var{config}] [#:glibc glibc]
  3316. Return a service that runs libc's name service cache daemon (nscd) with the
  3317. given @var{config}---an @code{<nscd-configuration>} object.
  3318. @end deffn
  3319. @defvr {Scheme Variable} %nscd-default-configuration
  3320. This is the default @code{<nscd-configuration>} value (see below) used
  3321. by @code{nscd-service}. This uses the caches defined by
  3322. @var{%nscd-default-caches}; see below.
  3323. @end defvr
  3324. @deftp {Data Type} nscd-configuration
  3325. This is the type representing the name service cache daemon (nscd)
  3326. configuration.
  3327. @table @asis
  3328. @item @code{log-file} (default: @code{"/var/log/nscd.log"})
  3329. Name of nscd's log file. This is where debugging output goes when
  3330. @code{debug-level} is strictly positive.
  3331. @item @code{debug-level} (default: @code{0})
  3332. Integer denoting the debugging levels. Higher numbers mean more
  3333. debugging output is logged.
  3334. @item @code{caches} (default: @var{%nscd-default-caches})
  3335. List of @code{<nscd-cache>} objects denoting things to be cached; see
  3336. below.
  3337. @end table
  3338. @end deftp
  3339. @deftp {Data Type} nscd-cache
  3340. Data type representing a cache database of nscd and its parameters.
  3341. @table @asis
  3342. @item @code{database}
  3343. This is a symbol representing the name of the database to be cached.
  3344. Valid values are @code{passwd}, @code{group}, @code{hosts}, and
  3345. @code{services}, which designate the corresponding NSS database
  3346. (@pxref{NSS Basics,,, libc, The GNU C Library Reference Manual}).
  3347. @item @code{positive-time-to-live}
  3348. @itemx @code{negative-time-to-live} (default: @code{20})
  3349. A number representing the number of seconds during which a positive or
  3350. negative lookup result remains in cache.
  3351. @item @code{check-files?} (default: @code{#t})
  3352. Whether to check for updates of the files corresponding to
  3353. @var{database}.
  3354. For instance, when @var{database} is @code{hosts}, setting this flag
  3355. instructs nscd to check for updates in @file{/etc/hosts} and to take
  3356. them into account.
  3357. @item @code{persistent?} (default: @code{#t})
  3358. Whether the cache should be stored persistently on disk.
  3359. @item @code{shared?} (default: @code{#t})
  3360. Whether the cache should be shared among users.
  3361. @item @code{max-database-size} (default: 32@tie{}MiB)
  3362. Maximum size in bytes of the database cache.
  3363. @c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert
  3364. @c settings, so leave them out.
  3365. @end table
  3366. @end deftp
  3367. @defvr {Scheme Variable} %nscd-default-caches
  3368. List of @code{<nscd-cache>} objects used by default by
  3369. @code{nscd-configuration} (see above.)
  3370. It enables persistent and aggressive caching of service and host name
  3371. lookups. The latter provides better host name lookup performance,
  3372. resilience in the face of unreliable name servers, and also better
  3373. privacy---often the result of host name lookups is in local cache, so
  3374. external name servers do not even need to be queried.
  3375. @end defvr
  3376. @deffn {Monadic Procedure} syslog-service
  3377. Return a service that runs @code{syslogd} with reasonable default
  3378. settings.
  3379. @end deffn
  3380. @deffn {Monadic Procedure} guix-service [#:guix guix] @
  3381. [#:builder-group "guixbuild"] [#:build-accounts 10] @
  3382. [#:authorize-hydra-key? #f] [#:use-substitutes? #t] @
  3383. [#:extra-options '()]
  3384. Return a service that runs the build daemon from @var{guix}, and has
  3385. @var{build-accounts} user accounts available under @var{builder-group}.
  3386. When @var{authorize-hydra-key?} is true, the @code{} public key
  3387. provided by @var{guix} is authorized upon activation, meaning that substitutes
  3388. from @code{} are used by default.
  3389. If @var{use-substitutes?} is false, the daemon is run with
  3390. @option{--no-substitutes} (@pxref{Invoking guix-daemon,
  3391. @option{--no-substitutes}}).
  3392. Finally, @var{extra-options} is a list of additional command-line options
  3393. passed to @command{guix-daemon}.
  3394. @end deffn
  3395. @deffn {Monadic Procedure} udev-service [#:udev udev]
  3396. Run @var{udev}, which populates the @file{/dev} directory dynamically.
  3397. @end deffn
  3398. @node Networking Services
  3399. @subsubsection Networking Services
  3400. The @code{(gnu services networking)} module provides services to configure
  3401. the network interface.
  3402. @cindex DHCP, networking service
  3403. @deffn {Monadic Procedure} dhcp-client-service [#:dhcp @var{isc-dhcp}]
  3404. Return a service that runs @var{dhcp}, a Dynamic Host Configuration
  3405. Protocol (DHCP) client, on all the non-loopback network interfaces.
  3406. @end deffn
  3407. @deffn {Monadic Procedure} static-networking-service @var{interface} @var{ip} @
  3408. [#:gateway #f] [#:name-services @code{'()}]
  3409. Return a service that starts @var{interface} with address @var{ip}. If
  3410. @var{gateway} is true, it must be a string specifying the default network
  3411. gateway.
  3412. @end deffn
  3413. @deffn {Monadic Procedure} ntp-service [#:ntp @var{ntp}] @
  3414. [#:name-service @var{%ntp-servers}]
  3415. Return a service that runs the daemon from @var{ntp}, the
  3416. @uref{, Network Time Protocol package}. The daemon will
  3417. keep the system clock synchronized with that of @var{servers}.
  3418. @end deffn
  3419. @defvr {Scheme Variable} %ntp-servers
  3420. List of host names used as the default NTP servers.
  3421. @end defvr
  3422. @deffn {Monadic Procedure} tor-service [#:tor tor]
  3423. Return a service to run the @uref{,Tor} daemon.
  3424. The daemon runs with the default settings (in particular the default exit
  3425. policy) as the @code{tor} unprivileged user.
  3426. @end deffn
  3427. @deffn {Monadic Procedure} bitlbee-service [#:bitlbee bitlbee] @
  3428. [#:interface ""] [#:port 6667] @
  3429. [#:extra-settings ""]
  3430. Return a service that runs @url{,BitlBee}, a daemon that
  3431. acts as a gateway between IRC and chat networks.
  3432. The daemon will listen to the interface corresponding to the IP address
  3433. specified in @var{interface}, on @var{port}. @code{} means that only
  3434. local clients can connect, whereas @code{} means that connections can
  3435. come from any networking interface.
  3436. In addition, @var{extra-settings} specifies a string to append to the
  3437. configuration file.
  3438. @end deffn
  3439. Furthermore, @code{(gnu services ssh)} provides the following service.
  3440. @deffn {Monadic Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
  3441. [#:interfaces '()] [#:port-number 22] @
  3442. [#:allow-empty-passwords? #f] [#:root-login? #f] @
  3443. [#:syslog-output? #t] [#:x11-forwarding? #t] @
  3444. [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @
  3445. [public-key-authentication? #t] [#:initialize? #f]
  3446. Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}.
  3447. @var{host-key} must designate a file containing the host key, and readable
  3448. only by root.
  3449. When @var{initialize?} is true, automatically create the seed and host key
  3450. upon service activation if they do not exist yet. This may take long and
  3451. require interaction.
  3452. When @var{initialize?} is false, it is up to the user to initialize the
  3453. randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
  3454. a key pair with the private key stored in file @var{host-key} (@pxref{lshd
  3455. basics,,, lsh, LSH Manual}).
  3456. When @var{interfaces} is empty, lshd listens for connections on all the
  3457. network interfaces; otherwise, @var{interfaces} must be a list of host names
  3458. or addresses.
  3459. @var{allow-empty-passwords?} specifies whether to accept log-ins with empty
  3460. passwords, and @var{root-login?} specifies whether to accept log-ins as
  3461. root.
  3462. The other options should be self-descriptive.
  3463. @end deffn
  3464. @defvr {Scheme Variable} %facebook-host-aliases
  3465. This variable contains a string for use in @file{/etc/hosts}
  3466. (@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each
  3467. line contains a entry that maps a known server name of the Facebook
  3468. on-line service---e.g., @code{}---to the local
  3469. host---@code{} or its IPv6 equivalent, @code{::1}.
  3470. This variable is typically used in the @code{hosts-file} field of an
  3471. @code{operating-system} declaration (@pxref{operating-system Reference,
  3472. @file{/etc/hosts}}):
  3473. @example
  3474. (use-modules (gnu) (guix))
  3475. (operating-system
  3476. (host-name "mymachine")
  3477. ;; ...
  3478. (hosts-file
  3479. ;; Create a /etc/hosts file with aliases for "localhost"
  3480. ;; and "mymachine", as well as for Facebook servers.
  3481. (text-file "hosts"
  3482. (string-append (local-host-aliases host-name)
  3483. %facebook-host-aliases))))
  3484. @end example
  3485. This mechanism can prevent programs running locally, such as Web
  3486. browsers, from accessing Facebook.
  3487. @end defvr
  3488. @node X Window
  3489. @subsubsection X Window
  3490. Support for the X Window graphical display system---specifically
  3491. Xorg---is provided by the @code{(gnu services xorg)} module. Note that
  3492. there is no @code{xorg-service} procedure. Instead, the X server is
  3493. started by the @dfn{login manager}, currently SLiM.
  3494. @deffn {Monadic Procedure} slim-service [#:allow-empty-passwords? #f] @
  3495. [#:auto-login? #f] [#:default-user ""] [#:startx] @
  3496. [#:theme @var{%default-slim-theme}] @
  3497. [#:theme-name @var{%default-slim-theme-name}]
  3498. Return a service that spawns the SLiM graphical login manager, which in
  3499. turn starts the X display server with @var{startx}, a command as returned by
  3500. @code{xorg-start-command}.
  3501. When @var{allow-empty-passwords?} is true, allow logins with an empty
  3502. password. When @var{auto-login?} is true, log in automatically as
  3503. @var{default-user}.
  3504. If @var{theme} is @code{#f}, the use the default log-in theme; otherwise
  3505. @var{theme} must be a gexp denoting the name of a directory containing the
  3506. theme to use. In that case, @var{theme-name} specifies the name of the
  3507. theme.
  3508. @end deffn
  3509. @defvr {Scheme Variable} %default-theme
  3510. @defvrx {Scheme Variable} %default-theme-name
  3511. The G-Expression denoting the default SLiM theme and its name.
  3512. @end defvr
  3513. @deffn {Monadic Procedure} xorg-start-command [#:guile] @
  3514. [#:drivers '()] [#:resolutions '()] [#:xorg-server @var{xorg-server}]
  3515. Return a derivation that builds a @var{guile} script to start the X server
  3516. from @var{xorg-server}. Usually the X server is started by a login manager.
  3517. @var{drivers} must be either the empty list, in which case Xorg chooses a
  3518. graphics driver automatically, or a list of driver names that will be tried in
  3519. this order---e.g., @code{("modesetting" "vesa")}.
  3520. Likewise, when @var{resolutions} is the empty list, Xorg chooses an
  3521. appropriate screen resolution; otherwise, it must be a list of
  3522. resolutions---e.g., @code{((1024 768) (640 480))}.
  3523. @end deffn
  3524. @node Setuid Programs
  3525. @subsection Setuid Programs
  3526. @cindex setuid programs
  3527. Some programs need to run with ``root'' privileges, even when they are
  3528. launched by unprivileged users. A notorious example is the
  3529. @command{passwd} programs, which can users can run to change their
  3530. password, and which requires write access to the @file{/etc/passwd} and
  3531. @file{/etc/shadow} files---something normally restricted to root, for
  3532. obvious security reasons. To address that, these executables are
  3533. @dfn{setuid-root}, meaning that they always run with root privileges
  3534. (@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual},
  3535. for more info about the setuid mechanisms.)
  3536. The store itself @emph{cannot} contain setuid programs: that would be a
  3537. security issue since any user on the system can write derivations that
  3538. populate the store (@pxref{The Store}). Thus, a different mechanism is
  3539. used: instead of changing the setuid bit directly on files that are in
  3540. the store, we let the system administrator @emph{declare} which programs
  3541. should be setuid root.
  3542. The @code{setuid-programs} field of an @code{operating-system}
  3543. declaration contains a list of G-expressions denoting the names of
  3544. programs to be setuid-root (@pxref{Using the Configuration System}).
  3545. For instance, the @command{passwd} program, which is part of the Shadow
  3546. package, can be designated by this G-expression (@pxref{G-Expressions}):
  3547. @example
  3548. #~(string-append #$shadow "/bin/passwd")
  3549. @end example
  3550. A default set of setuid programs is defined by the
  3551. @code{%setuid-programs} variable of the @code{(gnu system)} module.
  3552. @defvr {Scheme Variable} %setuid-programs
  3553. A list of G-expressions denoting common programs that are setuid-root.
  3554. The list includes commands such as @command{passwd}, @command{ping},
  3555. @command{su}, and @command{sudo}.
  3556. @end defvr
  3557. Under the hood, the actual setuid programs are created in the
  3558. @file{/run/setuid-programs} directory at system activation time. The
  3559. files in this directory refer to the ``real'' binaries, which are in the
  3560. store.
  3561. @node Initial RAM Disk
  3562. @subsection Initial RAM Disk
  3563. @cindex initial RAM disk (initrd)
  3564. @cindex initrd (initial RAM disk)
  3565. For bootstrapping purposes, the Linux-Libre kernel is passed an
  3566. @dfn{initial RAM disk}, or @dfn{initrd}. An initrd contains a temporary
  3567. root file system, as well as an initialization script. The latter is
  3568. responsible for mounting the real root file system, and for loading any
  3569. kernel modules that may be needed to achieve that.
  3570. The @code{initrd} field of an @code{operating-system} declaration allows
  3571. you to specify which initrd you would like to use. The @code{(gnu
  3572. system linux-initrd)} module provides two ways to build an initrd: the
  3573. high-level @code{base-initrd} procedure, and the low-level
  3574. @code{expression->initrd} procedure.
  3575. The @code{base-initrd} procedure is intended to cover most common uses.
  3576. For example, if you want to add a bunch of kernel modules to be loaded
  3577. at boot time, you can define the @code{initrd} field of the operating
  3578. system declaration like this:
  3579. @example
  3580. (initrd (lambda (file-systems . rest)
  3581. (apply base-initrd file-systems
  3582. #:extra-modules '("my.ko" "modules.ko")
  3583. rest)))
  3584. @end example
  3585. The @code{base-initrd} procedure also handles common use cases that
  3586. involves using the system as a QEMU guest, or as a ``live'' system whose
  3587. root file system is volatile.
  3588. @deffn {Monadic Procedure} base-initrd @var{file-systems} @
  3589. [#:qemu-networking? #f] [#:virtio? #f] [#:volatile-root? #f] @
  3590. [#:extra-modules '()] [#:mapped-devices '()]
  3591. Return a monadic derivation that builds a generic initrd. @var{file-systems} is
  3592. a list of file-systems to be mounted by the initrd, possibly in addition to
  3593. the root file system specified on the kernel command line via @code{--root}.
  3594. @var{mapped-devices} is a list of device mappings to realize before
  3595. @var{file-systems} are mounted (@pxref{Mapped Devices}).
  3596. When @var{qemu-networking?} is true, set up networking with the standard QEMU
  3597. parameters. When @var{virtio?} is true, load additional modules so the initrd can
  3598. be used as a QEMU guest with para-virtualized I/O drivers.
  3599. When @var{volatile-root?} is true, the root file system is writable but any changes
  3600. to it are lost.
  3601. The initrd is automatically populated with all the kernel modules necessary
  3602. for @var{file-systems} and for the given options. However, additional kernel
  3603. modules can be listed in @var{extra-modules}. They will be added to the initrd, and
  3604. loaded at boot time in the order in which they appear.
  3605. @end deffn
  3606. Needless to say, the initrds we produce and use embed a
  3607. statically-linked Guile, and the initialization program is a Guile
  3608. program. That gives a lot of flexibility. The
  3609. @code{expression->initrd} procedure builds such an initrd, given the
  3610. program to run in that initrd.
  3611. @deffn {Monadic Procedure} expression->initrd @var{exp} @
  3612. [#:guile %guile-static-stripped] [#:name "guile-initrd"] @
  3613. [#:modules '()]
  3614. Return a derivation that builds a Linux initrd (a gzipped cpio archive)
  3615. containing @var{guile} and that evaluates @var{exp}, a G-expression,
  3616. upon booting. All the derivations referenced by @var{exp} are
  3617. automatically copied to the initrd.
  3618. @var{modules} is a list of Guile module names to be embedded in the
  3619. initrd.
  3620. @end deffn
  3621. @node GRUB Configuration
  3622. @subsection GRUB Configuration
  3623. @cindex GRUB
  3624. @cindex boot loader
  3625. The operating system uses GNU@tie{}GRUB as its boot loader
  3626. (@pxref{Overview, overview of GRUB,, grub, GNU GRUB Manual}). It is
  3627. configured using @code{grub-configuration} declarations. This data type
  3628. is exported by the @code{(gnu system grub)} module, and described below.
  3629. @deftp {Data Type} grub-configuration
  3630. The type of a GRUB configuration declaration.
  3631. @table @asis
  3632. @item @code{device}
  3633. This is a string denoting the boot device. It must be a device name
  3634. understood by the @command{grub-install} command, such as
  3635. @code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
  3636. GNU GRUB Manual}).
  3637. @item @code{menu-entries} (default: @code{()})
  3638. A possibly empty list of @code{menu-entry} objects (see below), denoting
  3639. entries to appear in the GRUB boot menu, in addition to the current
  3640. system entry and the entry pointing to previous system generations.
  3641. @item @code{default-entry} (default: @code{0})
  3642. The index of the default boot menu entry. Index 0 is for the current
  3643. system's entry.
  3644. @item @code{timeout} (default: @code{5})
  3645. The number of seconds to wait for keyboard input before booting. Set to
  3646. 0 to boot immediately, and to -1 to wait indefinitely.
  3647. @item @code{theme} (default: @var{%default-theme})
  3648. The @code{grub-theme} object describing the theme to use.
  3649. @end table
  3650. @end deftp
  3651. Should you want to list additional boot menu entries @i{via} the
  3652. @code{menu-entries} field above, you will need to create them with the
  3653. @code{menu-entry} form:
  3654. @deftp {Data Type} menu-entry
  3655. The type of an entry in the GRUB boot menu.
  3656. @table @asis
  3657. @item @code{label}
  3658. The label to show in the menu---e.g., @code{"GNU System"}.
  3659. @item @code{linux}
  3660. The Linux kernel to boot.
  3661. @item @code{linux-arguments} (default: @code{()})
  3662. The list of extra Linux kernel command-line arguments---e.g.,
  3663. @code{("console=ttyS0")}.
  3664. @item @code{initrd}
  3665. A G-Expression or string denoting the file name of the initial RAM disk
  3666. to use (@pxref{G-Expressions}).
  3667. @end table
  3668. @end deftp
  3669. @c FIXME: Write documentation once it's stable.
  3670. Themes are created using the @code{grub-theme} form, which is not
  3671. documented yet.
  3672. @defvr {Scheme Variable} %default-theme
  3673. This is the default GRUB theme used by the operating system, with a
  3674. fancy background image displaying the GNU and Guix logos.
  3675. @end defvr
  3676. @node Invoking guix system
  3677. @subsection Invoking @code{guix system}
  3678. Once you have written an operating system declaration, as seen in the
  3679. previous section, it can be @dfn{instantiated} using the @command{guix
  3680. system} command. The synopsis is:
  3681. @example
  3682. guix system @var{options}@dots{} @var{action} @var{file}
  3683. @end example
  3684. @var{file} must be the name of a file containing an
  3685. @code{operating-system} declaration. @var{action} specifies how the
  3686. operating system is instantiate. Currently the following values are
  3687. supported:
  3688. @table @code
  3689. @item reconfigure
  3690. Build the operating system described in @var{file}, activate it, and
  3691. switch to it@footnote{This action is usable only on systems already
  3692. running GNU.}.
  3693. This effects all the configuration specified in @var{file}: user
  3694. accounts, system services, global package list, setuid programs, etc.
  3695. It also adds a GRUB menu entry for the new OS configuration, and moves
  3696. entries for older configurations to a submenu---unless
  3697. @option{--no-grub} is passed.
  3698. @c The paragraph below refers to the problem discussed at
  3699. @c <>.
  3700. It is highly recommended to run @command{guix pull} once before you run
  3701. @command{guix system reconfigure} for the first time (@pxref{Invoking
  3702. guix pull}). Failing to do that you would see an older version of Guix
  3703. once @command{reconfigure} has completed.
  3704. @item build
  3705. Build the operating system's derivation, which includes all the
  3706. configuration files and programs needed to boot and run the system.
  3707. This action does not actually install anything.
  3708. @item init
  3709. Populate the given directory with all the files necessary to run the
  3710. operating system specified in @var{file}. This is useful for first-time
  3711. installations of the GNU system. For instance:
  3712. @example
  3713. guix system init my-os-config.scm /mnt
  3714. @end example
  3715. copies to @file{/mnt} all the store items required by the configuration
  3716. specified in @file{my-os-config.scm}. This includes configuration
  3717. files, packages, and so on. It also creates other essential files
  3718. needed for the system to operate correctly---e.g., the @file{/etc},
  3719. @file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
  3720. This command also installs GRUB on the device specified in
  3721. @file{my-os-config}, unless the @option{--no-grub} option was passed.
  3722. @item vm
  3723. @cindex virtual machine
  3724. @cindex VM
  3725. Build a virtual machine that contain the operating system declared in
  3726. @var{file}, and return a script to run that virtual machine (VM).
  3727. Arguments given to the script are passed as is to QEMU.
  3728. The VM shares its store with the host system.
  3729. Additional file systems can be shared between the host and the VM using
  3730. the @code{--share} and @code{--expose} command-line options: the former
  3731. specifies a directory to be shared with write access, while the latter
  3732. provides read-only access to the shared directory.
  3733. The example below creates a VM in which the user's home directory is
  3734. accessible read-only, and where the @file{/exchange} directory is a
  3735. read-write mapping of the host's @file{$HOME/tmp}:
  3736. @example
  3737. guix system vm my-config.scm \
  3738. --expose=$HOME --share=$HOME/tmp=/exchange
  3739. @end example
  3740. On GNU/Linux, the default is to boot directly to the kernel; this has
  3741. the advantage of requiring only a very tiny root disk image since the
  3742. host's store can then be mounted.
  3743. The @code{--full-boot} option forces a complete boot sequence, starting
  3744. with the bootloader. This requires more disk space since a root image
  3745. containing at least the kernel, initrd, and bootloader data files must
  3746. be created. The @code{--image-size} option can be used to specify the
  3747. image's size.
  3748. @item vm-image
  3749. @itemx disk-image
  3750. Return a virtual machine or disk image of the operating system declared
  3751. in @var{file} that stands alone. Use the @option{--image-size} option
  3752. to specify the size of the image.
  3753. When using @code{vm-image}, the returned image is in qcow2 format, which
  3754. the QEMU emulator can efficiently use.
  3755. When using @code{disk-image}, a raw disk image is produced; it can be
  3756. copied as is to a USB stick, for instance. Assuming @code{/dev/sdc} is
  3757. the device corresponding to a USB stick, one can copy the image on it
  3758. using the following command:
  3759. @example
  3760. # dd if=$(guix system disk-image my-os.scm) of=/dev/sdc
  3761. @end example
  3762. @end table
  3763. @var{options} can contain any of the common build options provided by
  3764. @command{guix build} (@pxref{Invoking guix build}). In addition,
  3765. @var{options} can contain one of the following:
  3766. @table @option
  3767. @item --system=@var{system}
  3768. @itemx -s @var{system}
  3769. Attempt to build for @var{system} instead of the host's system type.
  3770. This works as per @command{guix build} (@pxref{Invoking guix build}).
  3771. @item --image-size=@var{size}
  3772. For the @code{vm-image} and @code{disk-image} actions, create an image
  3773. of the given @var{size}. @var{size} may be a number of bytes, or it may
  3774. include a unit as a suffix (@pxref{Block size, size specifications,,
  3775. coreutils, GNU Coreutils}).
  3776. @end table
  3777. Note that all the actions above, except @code{build} and @code{init},
  3778. rely on KVM support in the Linux-Libre kernel. Specifically, the
  3779. machine should have hardware virtualization support, the corresponding
  3780. KVM kernel module should be loaded, and the @file{/dev/kvm} device node
  3781. must exist and be readable and writable by the user and by the daemon's
  3782. build users.
  3783. @node Defining Services
  3784. @subsection Defining Services
  3785. The @code{(gnu services @dots{})} modules define several procedures that allow
  3786. users to declare the operating system's services (@pxref{Using the
  3787. Configuration System}). These procedures are @emph{monadic
  3788. procedures}---i.e., procedures that return a monadic value in the store
  3789. monad (@pxref{The Store Monad}). For examples of such procedures,
  3790. @xref{Services}.
  3791. @cindex service definition
  3792. The monadic value returned by those procedures is a @dfn{service
  3793. definition}---a structure as returned by the @code{service} form.
  3794. Service definitions specifies the inputs the service depends on, and an
  3795. expression to start and stop the service. Behind the scenes, service
  3796. definitions are ``translated'' into the form suitable for the
  3797. configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU
  3798. dmd Manual}).
  3799. As an example, here is what the @code{nscd-service} procedure looks
  3800. like:
  3801. @lisp
  3802. (define (nscd-service)
  3803. (with-monad %store-monad
  3804. (return (service
  3805. (documentation "Run libc's name service cache daemon.")
  3806. (provision '(nscd))
  3807. (activate #~(begin
  3808. (use-modules (guix build utils))
  3809. (mkdir-p "/var/run/nscd")))
  3810. (start #~(make-forkexec-constructor
  3811. (string-append #$glibc "/sbin/nscd")
  3812. "-f" "/dev/null" "--foreground"))
  3813. (stop #~(make-kill-destructor))
  3814. (respawn? #f)))))
  3815. @end lisp
  3816. @noindent
  3817. The @code{activate}, @code{start}, and @code{stop} fields are G-expressions
  3818. (@pxref{G-Expressions}). The @code{activate} field contains a script to
  3819. run at ``activation'' time; it makes sure that the @file{/var/run/nscd}
  3820. directory exists before @command{nscd} is started.
  3821. The @code{start} and @code{stop} fields refer to dmd's facilities to
  3822. start and stop processes (@pxref{Service De- and Constructors,,, dmd,
  3823. GNU dmd Manual}). The @code{provision} field specifies the name under
  3824. which this service is known to dmd, and @code{documentation} specifies
  3825. on-line documentation. Thus, the commands @command{deco start ncsd},
  3826. @command{deco stop nscd}, and @command{deco doc nscd} will do what you
  3827. would expect (@pxref{Invoking deco,,, dmd, GNU dmd Manual}).
  3828. @node Installing Debugging Files
  3829. @section Installing Debugging Files
  3830. @cindex debugging files
  3831. Program binaries, as produced by the GCC compilers for instance, are
  3832. typically written in the ELF format, with a section containing
  3833. @dfn{debugging information}. Debugging information is what allows the
  3834. debugger, GDB, to map binary code to source code; it is required to
  3835. debug a compiled program in good conditions.
  3836. The problem with debugging information is that is takes up a fair amount
  3837. of disk space. For example, debugging information for the GNU C Library
  3838. weighs in at more than 60 MiB. Thus, as a user, keeping all the
  3839. debugging info of all the installed programs is usually not an option.
  3840. Yet, space savings should not come at the cost of an impediment to
  3841. debugging---especially in the GNU system, which should make it easier
  3842. for users to exert their computing freedom (@pxref{GNU Distribution}).
  3843. Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
  3844. mechanism that allows users to get the best of both worlds: debugging
  3845. information can be stripped from the binaries and stored in separate
  3846. files. GDB is then able to load debugging information from those files,
  3847. when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
  3848. with GDB}).
  3849. The GNU distribution takes advantage of this by storing debugging
  3850. information in the @code{lib/debug} sub-directory of a separate package
  3851. output unimaginatively called @code{debug} (@pxref{Packages with
  3852. Multiple Outputs}). Users can choose to install the @code{debug} output
  3853. of a package when they need it. For instance, the following command
  3854. installs the debugging information for the GNU C Library and for GNU
  3855. Guile:
  3856. @example
  3857. guix package -i glibc:debug guile:debug
  3858. @end example
  3859. GDB must then be told to look for debug files in the user's profile, by
  3860. setting the @code{debug-file-directory} variable (consider setting it
  3861. from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
  3862. GDB}):
  3863. @example
  3864. (gdb) set debug-file-directory ~/.guix-profile/lib/debug
  3865. @end example
  3866. From there on, GDB will pick up debugging information from the
  3867. @code{.debug} files under @file{~/.guix-profile/lib/debug}.
  3868. In addition, you will most likely want GDB to be able to show the source
  3869. code being debugged. To do that, you will have to unpack the source
  3870. code of the package of interest (obtained with @code{guix build
  3871. --source}, @pxref{Invoking guix build}), and to point GDB to that source
  3872. directory using the @code{directory} command (@pxref{Source Path,
  3873. @code{directory},, gdb, Debugging with GDB}).
  3874. @c XXX: keep me up-to-date
  3875. The @code{debug} output mechanism in Guix is implemented by the
  3876. @code{gnu-build-system} (@pxref{Build Systems}). Currently, it is
  3877. opt-in---debugging information is available only for those packages
  3878. whose definition explicitly declares a @code{debug} output. This may be
  3879. changed to opt-out in the future, if our build farm servers can handle
  3880. the load. To check whether a package has a @code{debug} output, use
  3881. @command{guix package --list-available} (@pxref{Invoking guix package}).
  3882. @node Security Updates
  3883. @section Security Updates
  3884. @quotation Note
  3885. As of version @value{VERSION}, the feature described in this section is
  3886. experimental.
  3887. @end quotation
  3888. @cindex security updates
  3889. Occasionally, important security vulnerabilities are discovered in core
  3890. software packages and must be patched. Guix follows a functional
  3891. package management discipline (@pxref{Introduction}), which implies
  3892. that, when a package is changed, @emph{every package that depends on it}
  3893. must be rebuilt. This can significantly slow down the deployment of
  3894. fixes in core packages such as libc or Bash, since basically the whole
  3895. distribution would need to be rebuilt. Using pre-built binaries helps
  3896. (@pxref{Substitutes}), but deployment may still take more time than
  3897. desired.
  3898. @cindex grafts
  3899. To address that, Guix implements @dfn{grafts}, a mechanism that allows
  3900. for fast deployment of critical updates without the costs associated
  3901. with a whole-distribution rebuild. The idea is to rebuild only the
  3902. package that needs to be patched, and then to ``graft'' it onto packages
  3903. explicitly installed by the user and that were previously referring to
  3904. the original package. The cost of grafting is typically very low, and
  3905. order of magnitudes lower than a full rebuild of the dependency chain.
  3906. @cindex replacements of packages, for grafts
  3907. For instance, suppose a security update needs to be applied to Bash.
  3908. Guix developers will provide a package definition for the ``fixed''
  3909. Bash, say @var{bash-fixed}, in the usual way (@pxref{Defining
  3910. Packages}). Then, the original package definition is augmented with a
  3911. @code{replacement} field pointing to the package containing the bug fix:
  3912. @example
  3913. (define bash
  3914. (package
  3915. (name "bash")
  3916. ;; @dots{}
  3917. (replacement bash-fixed)))
  3918. @end example
  3919. From there on, any package depending directly or indirectly on Bash that
  3920. is installed will automatically be ``rewritten'' to refer to
  3921. @var{bash-fixed} instead of @var{bash}. This grafting process takes
  3922. time proportional to the size of the package, but expect less than a
  3923. minute for an ``average'' package on a recent machine.
  3924. Currently, the graft and the package it replaces (@var{bash-fixed} and
  3925. @var{bash} in the example above) must have the exact same @code{name}
  3926. and @code{version} fields. This restriction mostly comes from the fact
  3927. that grafting works by patching files, including binary files, directly.
  3928. Other restrictions may apply: for instance, when adding a graft to a
  3929. package providing a shared library, the original shared library and its
  3930. replacement must have the same @code{SONAME} and be binary-compatible.
  3931. @node Package Modules
  3932. @section Package Modules
  3933. From a programming viewpoint, the package definitions of the
  3934. GNU distribution are provided by Guile modules in the @code{(gnu packages
  3935. @dots{})} name space@footnote{Note that packages under the @code{(gnu
  3936. packages @dots{})} module name space are not necessarily ``GNU
  3937. packages''. This module naming scheme follows the usual Guile module
  3938. naming convention: @code{gnu} means that these modules are distributed
  3939. as part of the GNU system, and @code{packages} identifies modules that
  3940. define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
  3941. Reference Manual}). For instance, the @code{(gnu packages emacs)}
  3942. module exports a variable named @code{emacs}, which is bound to a
  3943. @code{<package>} object (@pxref{Defining Packages}).
  3944. The @code{(gnu packages @dots{})} module name space is
  3945. automatically scanned for packages by the command-line tools. For
  3946. instance, when running @code{guix package -i emacs}, all the @code{(gnu
  3947. packages @dots{})} modules are scanned until one that exports a package
  3948. object whose name is @code{emacs} is found. This package search
  3949. facility is implemented in the @code{(gnu packages)} module.
  3950. @cindex customization, of packages
  3951. @cindex package module search path
  3952. Users can store package definitions in modules with different
  3953. names---e.g., @code{(my-packages emacs)}. These package definitions
  3954. will not be visible by default. Thus, users can invoke commands such as
  3955. @command{guix package} and @command{guix build} have to be used with the
  3956. @code{-e} option so that they know where to find the package, or use the
  3957. @code{-L} option of these commands to make those modules visible
  3958. (@pxref{Invoking guix build, @code{--load-path}}), or define the
  3959. @code{GUIX_PACKAGE_PATH} environment variable. This environment
  3960. variable makes it easy to extend or customize the distribution and is
  3961. honored by all the user interfaces.
  3962. @defvr {Environment Variable} GUIX_PACKAGE_PATH
  3963. This is a colon-separated list of directories to search for package
  3964. modules. Directories listed in this variable take precedence over the
  3965. distribution's own modules.
  3966. @end defvr
  3967. The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
  3968. each package is built based solely on other packages in the
  3969. distribution. The root of this dependency graph is a small set of
  3970. @dfn{bootstrap binaries}, provided by the @code{(gnu packages
  3971. bootstrap)} module. For more information on bootstrapping,
  3972. @pxref{Bootstrapping}.
  3973. @node Packaging Guidelines
  3974. @section Packaging Guidelines
  3975. The GNU distribution is nascent and may well lack some of your favorite
  3976. packages. This section describes how you can help make the distribution
  3977. grow. @xref{Contributing}, for additional information on how you can
  3978. help.
  3979. Free software packages are usually distributed in the form of
  3980. @dfn{source code tarballs}---typically @file{tar.gz} files that contain
  3981. all the source files. Adding a package to the distribution means
  3982. essentially two things: adding a @dfn{recipe} that describes how to
  3983. build the package, including a list of other packages required to build
  3984. it, and adding @dfn{package meta-data} along with that recipe, such as a
  3985. description and licensing information.
  3986. In Guix all this information is embodied in @dfn{package definitions}.
  3987. Package definitions provide a high-level view of the package. They are
  3988. written using the syntax of the Scheme programming language; in fact,
  3989. for each package we define a variable bound to the package definition,
  3990. and export that variable from a module (@pxref{Package Modules}).
  3991. However, in-depth Scheme knowledge is @emph{not} a prerequisite for
  3992. creating packages. For more information on package definitions,
  3993. @pxref{Defining Packages}.
  3994. Once a package definition is in place, stored in a file in the Guix
  3995. source tree, it can be tested using the @command{guix build} command
  3996. (@pxref{Invoking guix build}). For example, assuming the new package is
  3997. called @code{gnew}, you may run this command from the Guix build tree:
  3998. @example
  3999. ./pre-inst-env guix build gnew --keep-failed
  4000. @end example
  4001. Using @code{--keep-failed} makes it easier to debug build failures since
  4002. it provides access to the failed build tree. Another useful
  4003. command-line option when debugging is @code{--log-file}, to access the
  4004. build log.
  4005. If the package is unknown to the @command{guix} command, it may be that
  4006. the source file contains a syntax error, or lacks a @code{define-public}
  4007. clause to export the package variable. To figure it out, you may load
  4008. the module from Guile to get more information about the actual error:
  4009. @example
  4010. ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
  4011. @end example
  4012. Once your package builds correctly, please send us a patch
  4013. (@pxref{Contributing}). Well, if you need help, we will be happy to
  4014. help you too. Once the patch is committed in the Guix repository, the
  4015. new package automatically gets built on the supported platforms by
  4016. @url{, our continuous integration
  4017. system}.
  4018. @cindex substituter
  4019. Users can obtain the new package definition simply by running
  4020. @command{guix pull} (@pxref{Invoking guix pull}). When
  4021. @code{} is done building the package, installing the
  4022. package automatically downloads binaries from there
  4023. (@pxref{Substitutes}). The only place where human intervention is
  4024. needed is to review and apply the patch.
  4025. @menu
  4026. * Software Freedom:: What may go into the distribution.
  4027. * Package Naming:: What's in a name?
  4028. * Version Numbers:: When the name is not enough.
  4029. * Python Modules:: Taming the snake.
  4030. * Perl Modules:: Little pearls.
  4031. * Fonts:: Fond of fonts.
  4032. @end menu
  4033. @node Software Freedom
  4034. @subsection Software Freedom
  4035. @c Adapted from
  4036. The GNU operating system has been developed so that users can have
  4037. freedom in their computing. GNU is @dfn{free software}, meaning that
  4038. users have the @url{,four
  4039. essential freedoms}: to run the program, to study and change the program
  4040. in source code form, to redistribute exact copies, and to distribute
  4041. modified versions. Packages found in the GNU distribution provide only
  4042. software that conveys these four freedoms.
  4043. In addition, the GNU distribution follow the
  4044. @url{,free
  4045. software distribution guidelines}. Among other things, these guidelines
  4046. reject non-free firmware, recommendations of non-free software, and
  4047. discuss ways to deal with trademarks and patents.
  4048. Some packages contain a small and optional subset that violates the
  4049. above guidelines, for instance because this subset is itself non-free
  4050. code. When that happens, the offending items are removed with
  4051. appropriate patches or code snippets in the package definition's
  4052. @code{origin} form (@pxref{Defining Packages}). That way, @code{guix
  4053. build --source} returns the ``freed'' source rather than the unmodified
  4054. upstream source.
  4055. @node Package Naming
  4056. @subsection Package Naming
  4057. A package has actually two names associated with it:
  4058. First, there is the name of the @emph{Scheme variable}, the one following
  4059. @code{define-public}. By this name, the package can be made known in the
  4060. Scheme code, for instance as input to another package. Second, there is
  4061. the string in the @code{name} field of a package definition. This name
  4062. is used by package management commands such as
  4063. @command{guix package} and @command{guix build}.
  4064. Both are usually the same and correspond to the lowercase conversion of
  4065. the project name chosen upstream, with underscores replaced with
  4066. hyphens. For instance, GNUnet is available as @code{gnunet}, and
  4067. SDL_net as @code{sdl-net}.
  4068. We do not add @code{lib} prefixes for library packages, unless these are
  4069. already part of the official project name. But @pxref{Python
  4070. Modules} and @ref{Perl Modules} for special rules concerning modules for
  4071. the Python and Perl languages.
  4072. Font package names are handled differently, @pxref{Fonts}.
  4073. @node Version Numbers
  4074. @subsection Version Numbers
  4075. We usually package only the latest version of a given free software
  4076. project. But sometimes, for instance for incompatible library versions,
  4077. two (or more) versions of the same package are needed. These require
  4078. different Scheme variable names. We use the name as defined
  4079. in @ref{Package Naming}
  4080. for the most recent version; previous versions use the same name, suffixed
  4081. by @code{-} and the smallest prefix of the version number that may
  4082. distinguish the two versions.
  4083. The name inside the package definition is the same for all versions of a
  4084. package and does not contain any version number.
  4085. For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
  4086. @example
  4087. (define-public gtk+
  4088. (package
  4089. (name "gtk+")
  4090. (version "3.9.12")
  4091. ...))
  4092. (define-public gtk+-2
  4093. (package
  4094. (name "gtk+")
  4095. (version "2.24.20")
  4096. ...))
  4097. @end example
  4098. If we also wanted GTK+ 3.8.2, this would be packaged as
  4099. @example
  4100. (define-public gtk+-3.8
  4101. (package
  4102. (name "gtk+")
  4103. (version "3.8.2")
  4104. ...))
  4105. @end example
  4106. @node Python Modules
  4107. @subsection Python Modules
  4108. We currently package Python 2 and Python 3, under the Scheme variable names
  4109. @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
  4110. To avoid confusion and naming clashes with other programming languages, it
  4111. seems desirable that the name of a package for a Python module contains
  4112. the word @code{python}.
  4113. Some modules are compatible with only one version of Python, others with both.
  4114. If the package Foo compiles only with Python 3, we name it
  4115. @code{python-foo}; if it compiles only with Python 2, we name it
  4116. @code{python2-foo}. If it is compatible with both versions, we create two
  4117. packages with the corresponding names.
  4118. If a project already contains the word @code{python}, we drop this;
  4119. for instance, the module python-dateutil is packaged under the names
  4120. @code{python-dateutil} and @code{python2-dateutil}.
  4121. @node Perl Modules
  4122. @subsection Perl Modules
  4123. Perl programs standing for themselves are named as any other package,
  4124. using the lowercase upstream name.
  4125. For Perl packages containing a single class, we use the lowercase class name,
  4126. replace all occurrences of @code{::} by dashes and prepend the prefix
  4127. @code{perl-}.
  4128. So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
  4129. Modules containing several classes keep their lowercase upstream name and
  4130. are also prepended by @code{perl-}. Such modules tend to have the word
  4131. @code{perl} somewhere in their name, which gets dropped in favor of the
  4132. prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
  4133. @node Fonts
  4134. @subsection Fonts
  4135. For fonts that are in general not installed by a user for typesetting
  4136. purposes, or that are distributed as part of a larger software package,
  4137. we rely on the general packaging rules for software; for instance, this
  4138. applies to the fonts delivered as part of the X.Org system or fonts that
  4139. are part of TeX Live.
  4140. To make it easier for a user to search for fonts, names for other packages
  4141. containing only fonts are constructed as follows, independently of the
  4142. upstream package name.
  4143. The name of a package containing only one font family starts with
  4144. @code{font-}; it is followed by the foundry name and a dash @code{-}
  4145. if the foundry is known, and the font family name, in which spaces are
  4146. replaced by dashes (and as usual, all upper case letters are transformed
  4147. to lower case).
  4148. For example, the Gentium font family by SIL is packaged under the name
  4149. @code{font-sil-gentium}.
  4150. For a package containing several font families, the name of the collection
  4151. is used in the place of the font family name.
  4152. For instance, the Liberation fonts consist of three families,
  4153. Liberation Sans, Liberation Serif and Liberation Mono.
  4154. These could be packaged separately under the names
  4155. @code{font-liberation-sans} and so on; but as they are distributed together
  4156. under a common name, we prefer to package them together as
  4157. @code{font-liberation}.
  4158. In the case where several formats of the same font family or font collection
  4159. are packaged separately, a short form of the format, prepended by a dash,
  4160. is added to the package name. We use @code{-ttf} for TrueType fonts,
  4161. @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
  4162. fonts.
  4163. @node Bootstrapping
  4164. @section Bootstrapping
  4165. @c Adapted from the ELS 2013 paper.
  4166. @cindex bootstrapping
  4167. Bootstrapping in our context refers to how the distribution gets built
  4168. ``from nothing''. Remember that the build environment of a derivation
  4169. contains nothing but its declared inputs (@pxref{Introduction}). So
  4170. there's an obvious chicken-and-egg problem: how does the first package
  4171. get built? How does the first compiler get compiled? Note that this is
  4172. a question of interest only to the curious hacker, not to the regular
  4173. user, so you can shamelessly skip this section if you consider yourself
  4174. a ``regular user''.
  4175. @cindex bootstrap binaries
  4176. The GNU system is primarily made of C code, with libc at its core. The
  4177. GNU build system itself assumes the availability of a Bourne shell and
  4178. command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
  4179. `grep'. Furthermore, build programs---programs that run
  4180. @code{./configure}, @code{make}, etc.---are written in Guile Scheme
  4181. (@pxref{Derivations}). Consequently, to be able to build anything at
  4182. all, from scratch, Guix relies on pre-built binaries of Guile, GCC,
  4183. Binutils, libc, and the other packages mentioned above---the
  4184. @dfn{bootstrap binaries}.
  4185. These bootstrap binaries are ``taken for granted'', though we can also
  4186. re-create them if needed (more on that later).
  4187. @unnumberedsubsec Preparing to Use the Bootstrap Binaries
  4188. @c As of Emacs 24.3, Info-mode displays the image, but since it's a
  4189. @c large image, it's hard to scroll. Oh well.
  4190. @image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}
  4191. The figure above shows the very beginning of the dependency graph of the
  4192. distribution, corresponding to the package definitions of the @code{(gnu
  4193. packages bootstrap)} module. At this level of detail, things are
  4194. slightly complex. First, Guile itself consists of an ELF executable,
  4195. along with many source and compiled Scheme files that are dynamically
  4196. loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz}
  4197. tarball shown in this graph. This tarball is part of Guix's ``source''
  4198. distribution, and gets inserted into the store with @code{add-to-store}
  4199. (@pxref{The Store}).
  4200. But how do we write a derivation that unpacks this tarball and adds it
  4201. to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv}
  4202. derivation---the first one that gets built---uses @code{bash} as its
  4203. builder, which runs @code{}, which in turn calls
  4204. @code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar},
  4205. @file{xz}, and @file{mkdir} are statically-linked binaries, also part of
  4206. the Guix source distribution, whose sole purpose is to allow the Guile
  4207. tarball to be unpacked.
  4208. Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
  4209. Guile that can be used to run subsequent build programs. Its first task
  4210. is to download tarballs containing the other pre-built binaries---this
  4211. is what the @code{.tar.xz.drv} derivations do. Guix modules such as
  4212. @code{ftp-client.scm} are used for this purpose. The
  4213. @code{module-import.drv} derivations import those modules in a directory
  4214. in the store, using the original layout. The
  4215. @code{module-import-compiled.drv} derivations compile those modules, and
  4216. write them in an output directory with the right layout. This
  4217. corresponds to the @code{#:modules} argument of
  4218. @code{build-expression->derivation} (@pxref{Derivations}).
  4219. Finally, the various tarballs are unpacked by the
  4220. derivations @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv},
  4221. etc., at which point we have a working C tool chain.
  4222. @unnumberedsubsec Building the Build Tools
  4223. @c TODO: Add a package-level dependency graph generated from (gnu
  4224. @c packages base).
  4225. Bootstrapping is complete when we have a full tool chain that does not
  4226. depend on the pre-built bootstrap tools discussed above. This
  4227. no-dependency requirement is verified by checking whether the files of
  4228. the final tool chain contain references to the @file{/gnu/store}
  4229. directories of the bootstrap inputs. The process that leads to this
  4230. ``final'' tool chain is described by the package definitions found in
  4231. the @code{(gnu packages commencement)} module.
  4232. @c See <>.
  4233. The first tool that gets built with the bootstrap binaries is
  4234. GNU Make, which is a prerequisite for all the following packages.
  4235. From there Findutils and Diffutils get built.
  4236. Then come the first-stage Binutils and GCC, built as pseudo cross
  4237. tools---i.e., with @code{--target} equal to @code{--host}. They are
  4238. used to build libc. Thanks to this cross-build trick, this libc is
  4239. guaranteed not to hold any reference to the initial tool chain.
  4240. From there the final Binutils and GCC are built. GCC uses @code{ld}
  4241. from the final Binutils, and links programs against the just-built libc.
  4242. This tool chain is used to build the other packages used by Guix and by
  4243. the GNU Build System: Guile, Bash, Coreutils, etc.
  4244. And voilà! At this point we have the complete set of build tools that
  4245. the GNU Build System expects. These are in the @code{%final-inputs}
  4246. variable of the @code{(gnu packages commencement)} module, and are
  4247. implicitly used by any package that uses @code{gnu-build-system}
  4248. (@pxref{Build Systems, @code{gnu-build-system}}).
  4249. @unnumberedsubsec Building the Bootstrap Binaries
  4250. Because the final tool chain does not depend on the bootstrap binaries,
  4251. those rarely need to be updated. Nevertheless, it is useful to have an
  4252. automated way to produce them, should an update occur, and this is what
  4253. the @code{(gnu packages make-bootstrap)} module provides.
  4254. The following command builds the tarballs containing the bootstrap
  4255. binaries (Guile, Binutils, GCC, libc, and a tarball containing a mixture
  4256. of Coreutils and other basic command-line tools):
  4257. @example
  4258. guix build bootstrap-tarballs
  4259. @end example
  4260. The generated tarballs are those that should be referred to in the
  4261. @code{(gnu packages bootstrap)} module mentioned at the beginning of
  4262. this section.
  4263. Still here? Then perhaps by now you've started to wonder: when do we
  4264. reach a fixed point? That is an interesting question! The answer is
  4265. unknown, but if you would like to investigate further (and have
  4266. significant computational and storage resources to do so), then let us
  4267. know.
  4268. @node Porting
  4269. @section Porting to a New Platform
  4270. As discussed above, the GNU distribution is self-contained, and
  4271. self-containment is achieved by relying on pre-built ``bootstrap
  4272. binaries'' (@pxref{Bootstrapping}). These binaries are specific to an
  4273. operating system kernel, CPU architecture, and application binary
  4274. interface (ABI). Thus, to port the distribution to a platform that is
  4275. not yet supported, one must build those bootstrap binaries, and update
  4276. the @code{(gnu packages bootstrap)} module to use them on that platform.
  4277. Fortunately, Guix can @emph{cross compile} those bootstrap binaries.
  4278. When everything goes well, and assuming the GNU tool chain supports the
  4279. target platform, this can be as simple as running a command like this
  4280. one:
  4281. @example
  4282. guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
  4283. @end example
  4284. For this to work, the @code{glibc-dynamic-linker} procedure in
  4285. @code{(gnu packages bootstrap)} must be augmented to return the right
  4286. file name for libc's dynamic linker on that platform; likewise,
  4287. @code{system->linux-architecture} in @code{(gnu packages linux)} must be
  4288. taught about the new platform.
  4289. Once these are built, the @code{(gnu packages bootstrap)} module needs
  4290. to be updated to refer to these binaries on the target platform. That
  4291. is, the hashes and URLs of the bootstrap tarballs for the new platform
  4292. must be added alongside those of the currently supported platforms. The
  4293. bootstrap Guile tarball is treated specially: it is expected to be
  4294. available locally, and @file{} has rules do download it for
  4295. the supported architectures; a rule for the new platform must be added
  4296. as well.
  4297. In practice, there may be some complications. First, it may be that the
  4298. extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
  4299. above) is not recognized by all the GNU tools. Typically, glibc
  4300. recognizes some of these, whereas GCC uses an extra @code{--with-abi}
  4301. configure flag (see @code{gcc.scm} for examples of how to handle this).
  4302. Second, some of the required packages could fail to build for that
  4303. platform. Lastly, the generated binaries could be broken for some
  4304. reason.
  4305. @c *********************************************************************
  4306. @node Contributing
  4307. @chapter Contributing
  4308. This project is a cooperative effort, and we need your help to make it
  4309. grow! Please get in touch with us on @email{} and
  4310. @code{#guix} on the Freenode IRC network. We welcome ideas, bug
  4311. reports, patches, and anything that may be helpful to the project. We
  4312. particularly welcome help on packaging (@pxref{Packaging Guidelines}).
  4313. Please see the
  4314. @url{,
  4315. @file{HACKING} file} that comes with the Guix source code for practical
  4316. details about contributions.
  4317. @c *********************************************************************
  4318. @node Acknowledgments
  4319. @chapter Acknowledgments
  4320. Guix is based on the Nix package manager, which was designed and
  4321. implemented by Eelco Dolstra, with contributions from other people (see
  4322. the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package
  4323. management, and promoted unprecedented features, such as transactional
  4324. package upgrades and rollbacks, per-user profiles, and referentially
  4325. transparent build processes. Without this work, Guix would not exist.
  4326. The Nix-based software distributions, Nixpkgs and NixOS, have also been
  4327. an inspiration for Guix.
  4328. GNU@tie{}Guix itself is a collective work with contributions from a
  4329. number of people. See the @file{AUTHORS} file in Guix for more
  4330. information on these fine people. The @file{THANKS} file lists people
  4331. who have helped by reporting bugs, taking care of the infrastructure,
  4332. providing artwork and themes, making suggestions, and more---thank you!
  4333. @c *********************************************************************
  4334. @node GNU Free Documentation License
  4335. @appendix GNU Free Documentation License
  4336. @include fdl-1.3.texi
  4337. @c *********************************************************************
  4338. @node Concept Index
  4339. @unnumbered Concept Index
  4340. @printindex cp
  4341. @node Programming Index
  4342. @unnumbered Programming Index
  4343. @syncodeindex tp fn
  4344. @syncodeindex vr fn
  4345. @printindex fn
  4346. @bye
  4347. @c Local Variables:
  4348. @c ispell-local-dictionary: "american";
  4349. @c End: