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.
 
 
 
 
 
 

8108 lines
308 KiB

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