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.

16065 lines
599 KiB

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