Mirror of GNU Guix
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.

1094 lines
42 KiB

  1. \input texinfo
  2. @c -*-texinfo-*-
  3. @c %**start of header
  4. @setfilename guix.info
  5. @documentencoding UTF-8
  6. @settitle GNU Guix Reference Manual
  7. @c %**end of header
  8. @include version.texi
  9. @set YEARS 2012, 2013
  10. @dircategory Package management
  11. @direntry
  12. * guix: (guix). Guix, the functional package manager.
  13. * guix-package: (guix)Invoking guix-package
  14. Managing packages with Guix.
  15. * guix-build: (guix)Invoking guix-build
  16. Building packages with Guix.
  17. @end direntry
  18. @titlepage
  19. @title{GNU Guix Reference Manual}
  20. @subtitle{Using the GNU Guix Functional Package Manager}
  21. @author Ludovic Courtès
  22. @page
  23. @vskip 0pt plus 1filll
  24. Edition @value{EDITION} @*
  25. @value{UPDATED} @*
  26. Copyright @copyright{} @value{YEARS} Ludovic Court@`es
  27. @quotation
  28. Permission is granted to copy, distribute and/or modify this document
  29. under the terms of the GNU Free Documentation License, Version 1.3 or
  30. any later version published by the Free Software Foundation; with no
  31. Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
  32. copy of the license is included in the section entitled ``GNU Free
  33. Documentation License''.
  34. @end quotation
  35. @end titlepage
  36. @copying
  37. This manual documents GNU Guix version @value{VERSION}.
  38. Copyright @copyright{} @value{YEARS} Ludovic Courtès
  39. Permission is granted to copy, distribute and/or modify this document
  40. under the terms of the GNU Free Documentation License, Version 1.3 or
  41. any later version published by the Free Software Foundation; with no
  42. Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
  43. copy of the license is included in the section entitled ``GNU Free
  44. Documentation License.''
  45. @end copying
  46. @contents
  47. @c *********************************************************************
  48. @node Top
  49. @top GNU Guix
  50. This document describes GNU Guix version @value{VERSION}, a functional
  51. package management tool written for the GNU system.
  52. @quotation
  53. Copyright @copyright{} @value{YEARS} Ludovic Courtès
  54. Permission is granted to copy, distribute and/or modify this document
  55. under the terms of the GNU Free Documentation License, Version 1.3 or
  56. any later version published by the Free Software Foundation; with no
  57. Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
  58. copy of the license is included in the section entitled ``GNU Free
  59. Documentation License.''
  60. @end quotation
  61. @menu
  62. * Introduction:: What is Guix about?
  63. * Installation:: Installing Guix.
  64. * Package Management:: Package installation, upgrade, etc.
  65. * Programming Interface:: Using Guix in Scheme.
  66. * Utilities:: Package management commands.
  67. * Acknowledgments:: Thanks!
  68. * GNU Free Documentation License:: The license of this manual.
  69. * Concept Index:: Concepts.
  70. * Function Index:: Functions.
  71. @end menu
  72. @c *********************************************************************
  73. @node Introduction
  74. @chapter Introduction
  75. GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
  76. using the international phonetic alphabet (IPA).} is a functional
  77. package management tool for the GNU system. Package management consists
  78. in all the activities that relate to building packages from source,
  79. honoring the build-time and run-time dependencies on packages,
  80. installing packages in user environments, upgrading installed packages
  81. to new versions or rolling back to a previous set, removing unused
  82. software packages, etc.
  83. @cindex functional package management
  84. The term @dfn{functional} refers to a specific package management
  85. discipline. In Guix, the package build and installation process is seen
  86. as a function, in the mathematical sense: that function takes inputs,
  87. such as build scripts, a compiler, and libraries depended on, and
  88. returns the installed package. As a pure function, its result depends
  89. solely on its inputs---for instance, it cannot refer to software or
  90. scripts that were not explicitly passed as inputs. A build function
  91. always produces the same result when passed a given set of inputs. Last
  92. but not least, a build function cannot alter the system's environment in
  93. any way; for instance, it cannot create, modify, or delete files outside
  94. of its build and installation directories. This is achieved by running
  95. build processes in dedicated ``chroots'', where only their explicit
  96. inputs are visible.
  97. @cindex store
  98. The result of package build functions is @dfn{cached} in the file
  99. system, in a special directory called @dfn{the store} (@pxref{The
  100. Store}). Each package is installed in a directory of its own, in the
  101. store---by default under @file{/nix/store}. The directory name contains
  102. a hash of all the inputs used to build that package; thus, changing an
  103. input yields a different directory name.
  104. This approach is the foundation of Guix's salient features: support for
  105. transactional package upgrades and rollback, per-user installation, and
  106. garbage collection of packages (@pxref{Features}).
  107. Guix has a command-line interface allowing users to build, install,
  108. upgrade, and remove packages, as well as a Scheme programming interface.
  109. The remainder of this manual describes them.
  110. @c *********************************************************************
  111. @node Installation
  112. @chapter Installation
  113. This section describes the software requirements of Guix, as well as how
  114. to install it and get ready to use it.
  115. The build procedure for Guix is the same as for other GNU software, and
  116. is not covered here. Please see the files @file{README} and
  117. @file{INSTALL} in the Guix source tree for additional details.
  118. @menu
  119. * Requirements:: Software needed to build and run Guix.
  120. * Setting Up the Daemon:: Preparing the build daemon's environment.
  121. * Invoking guix-daemon:: Running the build daemon.
  122. @end menu
  123. @node Requirements
  124. @section Requirements
  125. GNU Guix depends on the following packages:
  126. @itemize
  127. @item @url{http://gnu.org/software/guile/, GNU Guile 2.0.x};
  128. @item @url{http://gnupg.org/, GNU libgcrypt}
  129. @end itemize
  130. Unless @code{--disable-daemon} was passed to @command{configure}, the
  131. following packages are also needed:
  132. @itemize
  133. @item @url{http://sqlite.org, SQLite 3}
  134. @item @url{http://www.bzip.org, libbz2}
  135. @item @url{http://gcc.gnu.org, GCC's g++}
  136. @end itemize
  137. When a working installation of the Nix package manager is available, you
  138. can instead configure Guix with @code{--disable-daemon}. In that case,
  139. @url{http://nixos.org/nix/, Nix} replaces the three dependencies above.
  140. Guix is compatible with Nix, so it is possible to share the same store
  141. between both. To do so, you must pass @command{configure} not only the
  142. same @code{--with-store-dir} value, but also the same
  143. @code{--localstatedir} value (the latter is essential because it
  144. specifies where the database that store meta-data about the store is
  145. located, among other things.) The default values are
  146. @code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
  147. Note that @code{--disable-daemon} is orthogonal and is not required if
  148. your goal is to share the same store as Nix.
  149. @node Setting Up the Daemon
  150. @section Setting Up the Daemon
  151. @cindex daemon
  152. Operations such as building a package or running the garbage collector
  153. are all performed by a specialized process, the @dfn{Guix daemon}, on
  154. behalf of clients. Only the daemon may access the store and its
  155. associated database. Thus, any operation that manipulates the store
  156. goes through the daemon. For instance, command-line tools such as
  157. @command{guix-package} and @command{guix-build} communicate with the
  158. daemon (@i{via} remote procedure calls) to instruct it what to do.
  159. In a standard multi-user setup, Guix and its daemon---the
  160. @command{guix-daemon} program---are installed by the system
  161. administrator; @file{/nix/store} is owned by @code{root} and
  162. @command{guix-daemon} runs as @code{root}. Unprivileged users may use
  163. Guix tools to build packages or otherwise access the store, and the
  164. daemon will do it on their behalf, ensuring that the store is kept in a
  165. consistent state, and allowing built packages to be shared among users.
  166. @cindex build users
  167. When @command{guix-daemon} runs as @code{root}, you may not want package
  168. build processes themselves to run as @code{root} too, for obvious
  169. security reasons. To avoid that, a special pool of @dfn{build users}
  170. should be created for use by build processes started by the daemon.
  171. These build users need not have a shell and a home directory: they will
  172. just be used when the daemon drops @code{root} privileges in build
  173. processes. Having several such users allows the daemon to launch
  174. distinct build processes under separate UIDs, which guarantees that they
  175. do not interfere with each other---an essential feature since builds are
  176. regarded as pure functions (@pxref{Introduction}).
  177. On a GNU/Linux system, a build user pool may be created like this (using
  178. Bash syntax and the @code{shadow} commands):
  179. @example
  180. # groupadd guix-builder
  181. # for i in `seq 1 10`;
  182. do
  183. useradd -g guix-builder -d /var/empty -s `which nologin` \
  184. -c "Guix build user $i" guix-builder$i;
  185. done
  186. @end example
  187. @noindent
  188. The @code{guix-daemon} program may then be run as @code{root} with:
  189. @example
  190. # guix-daemon --build-users-group=guix-builder
  191. @end example
  192. Guix may also be used in a single-user setup, with @command{guix-daemon}
  193. running as an unprivileged user. However, to maximize non-interference
  194. of build processes, the daemon still needs to perform certain operations
  195. that are restricted to @code{root} on GNU/Linux: it should be able to
  196. run build processes in a chroot, and to run them under different UIDs.
  197. To that end, the @command{nix-setuid-helper} program is provided; it is
  198. a small C program (less than 300 lines) that, if it is made setuid
  199. @code{root}, can be executed by the daemon to perform these operations
  200. on its behalf. The @code{root}-owned @file{/etc/nix-setuid.conf} file
  201. is read by @command{nix-setuid-helper}; it should contain exactly two
  202. words: the user name under which the authorized @command{guix-daemon}
  203. runs, and the name of the build users group.
  204. If you are installing Guix as an unprivileged user and do not have the
  205. ability to make @file{nix-setuid-helper} setuid-@code{root}, it is still
  206. possible to run @command{guix-daemon}. However, build processes will
  207. not be isolated from one another, and not from the rest of the system.
  208. Thus, build processes may interfere with each other, and may access
  209. programs, libraries, and other files available on the system---making it
  210. much harder to view them as @emph{pure} functions.
  211. @node Invoking guix-daemon
  212. @section Invoking @command{guix-daemon}
  213. The @command{guix-daemon} program implements all the functionality to
  214. access the store. This includes launching build processes, running the
  215. garbage collector, querying the availability of a build result, etc. It
  216. is normally run as @code{root} like this:
  217. @example
  218. # guix-daemon --build-users-group=guix-builder
  219. @end example
  220. @noindent
  221. For details on how to set it up, @ref{Setting Up the Daemon}.
  222. By default, @command{guix-daemon} launches build processes under
  223. different UIDs, taken from the build group specified with
  224. @code{--build-users-group}. In addition, each build process is run in a
  225. chroot environment that only contains the subset of the store that the
  226. build process depends on, as specified by its derivation
  227. (@pxref{Programming Interface, derivation}), plus a set of specific
  228. system directories. By default, the latter contains @file{/dev} and
  229. @file{/dev/pts}.
  230. The following command-line options are supported:
  231. @table @code
  232. @item --build-users-group=@var{group}
  233. Take users from @var{group} to run build processes (@pxref{Setting Up
  234. the Daemon, build users}).
  235. @item --cache-failures
  236. Cache build failures. By default, only successful builds are cached.
  237. @item --cores=@var{n}
  238. @itemx -c @var{n}
  239. Use @var{n} CPU cores to build each derivation; @code{0} means as many
  240. as available.
  241. The default value is @code{1}, but it may be overridden by clients, such
  242. as the @code{--cores} option of @command{guix-build} (@pxref{Invoking
  243. guix-build}).
  244. The effect is to define the @code{NIX_BUILD_CORES} environment variable
  245. in the build process, which can then use it to exploit internal
  246. parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
  247. @item --max-jobs=@var{n}
  248. @itemx -M @var{n}
  249. Allow at most @var{n} build jobs in parallel. The default value is
  250. @code{1}.
  251. @item --debug
  252. Produce debugging output.
  253. This is useful to debug daemon start-up issues, but then it may be
  254. overridden by clients, for example the @code{--verbosity} option of
  255. @command{guix-build} (@pxref{Invoking guix-build}).
  256. @item --chroot-directory=@var{dir}
  257. Add @var{dir} to the build chroot.
  258. Doing this may change the result of build processes---for instance if
  259. they use optional dependencies found in @var{dir} when it is available,
  260. and not otherwise. For that reason, it is not recommended to do so.
  261. Instead, make sure that each derivation declares all the inputs that it
  262. needs.
  263. @item --disable-chroot
  264. Disable chroot builds.
  265. Using this option is not recommended since, again, it would allow build
  266. processes to gain access to undeclared dependencies.
  267. @item --disable-log-compression
  268. Disable compression of the build logs.
  269. Unless @code{--lose-logs} is used, all the build logs are kept in the
  270. @var{localstatedir}. To save space, the daemon automatically compresses
  271. them with bzip2 by default. This option disables that.
  272. @item --disable-store-optimization
  273. Disable automatic file ``deduplication'' in the store.
  274. By default, files added to the store are automatically ``deduplicated'':
  275. if a newly added file is identical as another one found in the store,
  276. the daemon makes the new file a hard link to the other file. This
  277. slightly increases the input/output load at the end of a build process.
  278. This option disables this.
  279. @item --impersonate-linux-2.6
  280. On Linux-based systems, impersonate Linux 2.6. This means that the
  281. kernel's @code{uname} system call will report 2.6 as the release number.
  282. This might be helpful to build programs that (usually wrongfully) depend
  283. on the kernel version number.
  284. @item --lose-logs
  285. Do not keep build logs. By default they are kept under
  286. @code{@var{localstatedir}/nix/log}.
  287. @item --system=@var{system}
  288. Assume @var{system} as the current system type. By default it is the
  289. architecture/kernel pair found at configure time, such as
  290. @code{x86_64-linux}.
  291. @end table
  292. @c *********************************************************************
  293. @node Package Management
  294. @chapter Package Management
  295. The purpose of GNU Guix is to allow users to easily install, upgrade, and
  296. remove software packages, without having to know about their build
  297. procedure or dependencies. Guix also goes beyond this obvious set of
  298. features.
  299. This chapter describes the main features of Guix, as well as the package
  300. management tools it provides.
  301. @menu
  302. * Features:: How Guix will make your life brighter.
  303. * Invoking guix-package:: Package installation, removal, etc.
  304. * Invoking guix-gc:: Running the garbage collector.
  305. @end menu
  306. @node Features
  307. @section Features
  308. When using Guix, each package ends up in the @dfn{package store}, in its
  309. own directory---something that resembles
  310. @file{/nix/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
  311. Instead of referring to these directories, users have their own
  312. @dfn{profile}, which points to the packages that they actually want to
  313. use. That profile is normally stored in @code{$HOME/.guix-profile}, and
  314. each user has its own profile.
  315. For example, if @code{alice} installed GCC 4.7.2, then
  316. @file{/home/alice/.guix-profile/bin/gcc} points to
  317. @file{/nix/store/xxx-gcc-4.7.2/bin/gcc}; on the same machine, @code{bob}
  318. may have installed GCC 4.8.0, in which case its profile refers to these
  319. particular package installation. Both coexist, without any
  320. interference.
  321. The @command{guix-package} command is the central tool to manage
  322. packages. It operates on those per-user profiles, and can be used
  323. @emph{with normal user privileges}.
  324. The command provides the obvious install, remove, and upgrade
  325. operations. Each invocation is actually a @emph{transaction}: either
  326. the specified operation succeeds, or nothing happens. Thus, if the
  327. @command{guix-package} processed is terminated during the transaction,
  328. or if a power outage occurs during the transaction, then the user's
  329. profile remains in its previous state, and remains usable.
  330. In addition, any package transaction may be @emph{rolled back}. So, if,
  331. for example, an upgrade installs a new version of a package that turns
  332. out to have a serious bug, users may roll back to the previous instance
  333. of their profile, which was known to work well.
  334. All those packages in the package store may be @emph{garbage-collected}.
  335. Guix can determine which packages are still referenced by the user
  336. profiles, and remove those that are provably no longer referenced
  337. (@pxref{Invoking guix-gc}). Users may also explicitly remove old
  338. generations of their profile so that the packages they refer to can be
  339. collected.
  340. Finally, Guix takes a @dfn{purely functional} approach to package
  341. management, as described in the introduction (@pxref{Introduction}).
  342. Each @file{/nix/store} package directory name contains a hash of all the
  343. inputs that were used to build that package---compiler, libraries, build
  344. scripts, etc. This direct correspondence allows users to make sure a
  345. given package installation matches the current state of their
  346. distribution.
  347. @c FIXME: Remove footnote when it's implemented.
  348. This foundation allows Guix to support @dfn{transparent binary/source
  349. deployment}@footnote{This feature is not implemented as of version
  350. @value{VERSION}. Please contact @email{bug-guix@@gnu.org} for more
  351. details.}. When a pre-built binary for a @file{/nix/store} path is
  352. available from an external source, Guix just downloads it; otherwise, it
  353. builds the package from source, locally.
  354. @node Invoking guix-package
  355. @section Invoking @command{guix-package}
  356. The @command{guix-package} command is the tool that allows users to
  357. install, upgrade, and remove packages, as well as rolling back to
  358. previous configurations. It operates only on the user's own profile,
  359. and works with normal user privileges (@pxref{Features}). Its syntax
  360. is:
  361. @example
  362. guix-package @var{options}
  363. @end example
  364. Primarily, @var{options} specifies the operations to be performed during
  365. the transaction. Upon completion, a new profile is created, but
  366. previous generations of the profile remain available, should the user
  367. want to roll back.
  368. For each user, a symlink to the user's default profile is automatically
  369. created in @file{$HOME/.guix-profile}. This symlink always points to the
  370. current generation of the user's default profile. Thus, users can add
  371. @file{$HOME/.guix-profile/bin} to their @code{PATH} environment
  372. variable, and so on.
  373. In a multi-user setup, user profiles must be stored in a place
  374. registered as a @dfn{garbage-collector root}, which
  375. @file{$HOME/.guix-profile} points to (@pxref{Invoking guix-gc}). That
  376. directory is normally
  377. @code{@var{localstatedir}/profiles/per-user/@var{user}}, where
  378. @var{localstatedir} is the value passed to @code{configure} as
  379. @code{--localstatedir}, and @var{user} is the user name. It must be
  380. created by @code{root}, with @var{user} as the owner. When it does not
  381. exist, @command{guix-package} emits an error about it.
  382. The @var{options} can be among the following:
  383. @table @code
  384. @item --install=@var{package}
  385. @itemx -i @var{package}
  386. Install @var{package}.
  387. @var{package} may specify either a simple package name, such as
  388. @code{guile}, or a package name followed by a hyphen and version number,
  389. such as @code{guile-1.8.8}. In addition, @var{package} may contain a
  390. colon, followed by the name of one of the outputs of the package, as in
  391. @code{gcc:doc} or @code{binutils-2.22:lib}.
  392. @item --remove=@var{package}
  393. @itemx -r @var{package}
  394. Remove @var{package}.
  395. @item --upgrade=@var{regexp}
  396. @itemx -u @var{regexp}
  397. Upgrade all the installed packages matching @var{regexp}.
  398. @item --roll-back
  399. Roll back to the previous @dfn{generation} of the profile---i.e., undo
  400. the last transaction.
  401. When combined with options such as @code{--install}, roll back occurs
  402. before any other actions.
  403. @item --profile=@var{profile}
  404. @itemx -p @var{profile}
  405. Use @var{profile} instead of the user's default profile.
  406. @item --dry-run
  407. @itemx -n
  408. Show what would be done without actually doing it.
  409. @item --verbose
  410. Produce verbose output. In particular, emit the environment's build log
  411. on the standard error port.
  412. @item --bootstrap
  413. Use the bootstrap Guile to build the profile. This option is only
  414. useful to distribution developers.
  415. @end table
  416. In addition to these actions @command{guix-package} supports the
  417. following options to query the current state of a profile, or the
  418. availability of packages:
  419. @table @option
  420. @item --list-installed[=@var{regexp}]
  421. @itemx -I [@var{regexp}]
  422. List currently installed packages in the specified profile. When
  423. @var{regexp} is specified, list only installed packages whose name
  424. matches @var{regexp}.
  425. For each installed package, print the following items, separated by
  426. tabs: the package name, its version string, the part of the package that
  427. is installed (for instance, @code{out} for the default output,
  428. @code{include} for its headers, etc.), and the path of this package in
  429. the store.
  430. @item --list-available[=@var{regexp}]
  431. @itemx -A [@var{regexp}]
  432. List packages currently available in the software distribution. When
  433. @var{regexp} is specified, list only installed packages whose name
  434. matches @var{regexp}.
  435. For each package, print the following items separated by tabs: its name,
  436. its version string, the parts of the package (@code{out} for the main
  437. files, @code{lib} for libraries and possibly headers, etc.), and the
  438. source location of its definition.
  439. @end table
  440. @node Invoking guix-gc
  441. @section Invoking @command{guix-gc}
  442. @cindex garbage collector
  443. Packages that are installed but not used may be @dfn{garbage-collected}.
  444. The @command{guix-gc} command allows users to explicitly run the garbage
  445. collector to reclaim space from the @file{/nix/store} directory.
  446. The garbage collector has a set of known @dfn{roots}: any file under
  447. @file{/nix/store} reachable from a root is considered @dfn{live} and
  448. cannot be deleted; any other file is considered @dfn{dead} and may be
  449. deleted. The set of garbage collector roots includes default user
  450. profiles, and may be augmented with @command{guix-build --root}, for
  451. example (@pxref{Invoking guix-build}).
  452. The @command{guix-gc} command has three modes of operation: it can be
  453. used to garbage-collect any dead files (the default), to delete specific
  454. files (the @code{--delete} option), or to print garbage-collector
  455. information. The available options are listed below:
  456. @table @code
  457. @item --collect-garbage[=@var{min}]
  458. @itemx -C [@var{min}]
  459. Collect garbage---i.e., unreachable @file{/nix/store} files and
  460. sub-directories. This is the default operation when no option is
  461. specified.
  462. When @var{min} is given, stop once @var{min} bytes have been collected.
  463. @var{min} may be a number of bytes, or it may include a unit as a
  464. suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes.
  465. When @var{min} is omitted, collect all the garbage.
  466. @item --delete
  467. @itemx -d
  468. Attempt to delete all the store files and directories specified as
  469. arguments. This fails if some of the files are not in the store, or if
  470. they are still live.
  471. @item --list-dead
  472. Show the list of dead files and directories still present in the
  473. store---i.e., files and directories no longer reachable from any root.
  474. @item --list-live
  475. Show the list of live store files and directories.
  476. @end table
  477. @c *********************************************************************
  478. @node Programming Interface
  479. @chapter Programming Interface
  480. GNU Guix provides several Scheme programming interfaces (APIs) to
  481. define, build, and query packages. The first interface allows users to
  482. write high-level package definitions. These definitions refer to
  483. familiar packaging concepts, such as the name and version of a package,
  484. its build system, and its dependencies. These definitions can then be
  485. turned into concrete build actions.
  486. Build actions are performed by the Guix daemon, on behalf of users. In a
  487. standard setup, the daemon has write access to the store---the
  488. @file{/nix/store} directory---whereas users do not. The recommended
  489. setup also has the daemon perform builds in chroots, under a specific
  490. build users, to minimize interference with the rest of the system.
  491. @cindex derivation
  492. Lower-level APIs are available to interact with the daemon and the
  493. store. To instruct the daemon to perform a build action, users actually
  494. provide it with a @dfn{derivation}. A derivation is a low-level
  495. representation of the build actions to be taken, and the environment in
  496. which they should occur---derivations are to package definitions what
  497. assembly is to C programs.
  498. This chapter describes all these APIs in turn, starting from high-level
  499. package definitions.
  500. @menu
  501. * Defining Packages:: Defining new packages.
  502. * The Store:: Manipulating the package store.
  503. * Derivations:: Low-level interface to package derivations.
  504. @end menu
  505. @node Defining Packages
  506. @section Defining Packages
  507. The high-level interface to package definitions is implemented in the
  508. @code{(guix packages)} and @code{(guix build-system)} modules. As an
  509. example, the package definition, or @dfn{recipe}, for the GNU Hello
  510. package looks like this:
  511. @example
  512. (use-modules (guix packages)
  513. (guix download)
  514. (guix build-system gnu)
  515. (guix licenses))
  516. (define hello
  517. (package
  518. (name "hello")
  519. (version "2.8")
  520. (source (origin
  521. (method url-fetch)
  522. (uri (string-append "mirror://gnu/hello/hello-" version
  523. ".tar.gz"))
  524. (sha256
  525. (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
  526. (build-system gnu-build-system)
  527. (inputs `(("gawk" ,gawk)))
  528. (synopsis "GNU Hello")
  529. (description "Yeah...")
  530. (home-page "http://www.gnu.org/software/hello/")
  531. (license gpl3+)))
  532. @end example
  533. @noindent
  534. Without being a Scheme expert, the reader may have guessed the meaning
  535. of the various fields here. This expression binds variable @var{hello}
  536. to a @code{<package>} object, which is essentially a record
  537. (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
  538. This package object can be inspected using procedures found in the
  539. @code{(guix packages)} module; for instance, @code{(package-name hello)}
  540. returns---surprise!---@code{"hello"}.
  541. There are a few points worth noting in the above package definition:
  542. @itemize
  543. @item
  544. The @code{source} field of the package is an @code{<origin>} object.
  545. Here, the @code{url-fetch} method from @code{(guix download)} is used,
  546. meaning that the source is a file to be downloaded over FTP or HTTP.
  547. The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
  548. the GNU mirrors defined in @code{(guix download)}.
  549. The @code{sha256} field specifies the expected SHA256 hash of the file
  550. being downloaded. It is mandatory, and allows Guix to check the
  551. integrity of the file. The @code{(base32 @dots{})} form introduces the
  552. base32 representation of the hash. A convenient way to obtain this
  553. information is with the @code{guix-download} tool.
  554. @item
  555. @cindex GNU Build System
  556. The @code{build-system} field is set to @var{gnu-build-system}. The
  557. @var{gnu-build-system} variable is defined in the @code{(guix
  558. build-system gnu)} module, and is bound to a @code{<build-system>}
  559. object.
  560. Naturally, @var{gnu-build-system} represents the familiar GNU Build
  561. System, and variants thereof (@pxref{Configuration, configuration and
  562. makefile conventions,, standards, GNU Coding Standards}). In a
  563. nutshell, packages using the GNU Build System may be configured, built,
  564. and installed with the usual @code{./configure && make && make check &&
  565. make install} command sequence. This is what @var{gnu-build-system}
  566. does.
  567. In addition, @var{gnu-build-system} ensures that the ``standard''
  568. environment for GNU packages is available. This includes tools such as
  569. GCC, Coreutils, Bash, Make, Diffutils, and Patch.
  570. @item
  571. The @code{inputs} field specifies inputs to the build process---i.e.,
  572. build-time or run-time dependencies of the package. Here, we define an
  573. input called @code{"gawk"} whose value is that of the @var{gawk}
  574. variable; @var{gawk} is itself bound to a @code{<package>} object.
  575. Note that GCC, Coreutils, Bash, and other essential tools do not need to
  576. be specified as inputs here. Instead, @var{gnu-build-system} takes care
  577. of ensuring that they are present.
  578. However, any other dependencies need to be specified in the
  579. @code{inputs} field. Any dependency not specified here will simply be
  580. unavailable to the build process, possibly leading to a build failure.
  581. @end itemize
  582. There are other fields that package definitions may provide. Of
  583. particular interest is the @code{arguments} field. When specified, it
  584. must be bound to a list of additional arguments to be passed to the
  585. build system. For instance, the above definition could be augmented
  586. with the following field initializer:
  587. @example
  588. (arguments `(#:tests? #f
  589. #:configure-flags '("--enable-silent-rules")))
  590. @end example
  591. @noindent
  592. These are keyword arguments (@pxref{Optional Arguments, keyword
  593. arguments in Guile,, guile, GNU Guile Reference Manual}). They are
  594. passed to @var{gnu-build-system}, which interprets them as meaning ``do
  595. not run @code{make check}'', and ``run @file{configure} with the
  596. @code{--enable-silent-rules} flag''. The value of these keyword
  597. parameters is actually evaluated in the @dfn{build stratum}---i.e., by a
  598. Guile process launched by the daemon (@pxref{Derivations}).
  599. Once a package definition is in place@footnote{Simple package
  600. definitions like the one above may be automatically converted from the
  601. Nixpkgs distribution using the @command{guix-import} command.}, the
  602. package may actually be built using the @code{guix-build} command-line
  603. tool (@pxref{Invoking guix-build}).
  604. Behind the scenes, a derivation corresponding to the @code{<package>}
  605. object is first computed by the @code{package-derivation} procedure.
  606. That derivation is stored in a @code{.drv} file under @file{/nix/store}.
  607. The build actions it prescribes may then be realized by using the
  608. @code{build-derivations} procedure (@pxref{The Store}).
  609. @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
  610. Return the derivation of @var{package} for @var{system}. The result is
  611. the file name of the derivation---i.e., a @code{.drv} file under
  612. @code{/nix/store}.
  613. @var{package} must be a valid @code{<package>} object, and @var{system}
  614. must be a string denoting the target system type---e.g.,
  615. @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
  616. must be a connection to the daemon, which operates on the store
  617. (@pxref{The Store}).
  618. @end deffn
  619. @node The Store
  620. @section The Store
  621. @cindex store
  622. @cindex store paths
  623. Conceptually, the @dfn{store} is where derivations that have been
  624. successfully built are stored---by default, under @file{/nix/store}.
  625. Sub-directories in the store are referred to as @dfn{store paths}. The
  626. store has an associated database that contains information such has the
  627. store paths referred to by each store path, and the list of @emph{valid}
  628. store paths---paths that result from a successful build.
  629. The store is always accessed by the daemon on behalf of its clients
  630. (@pxref{Invoking guix-daemon}). To manipulate the store, clients
  631. connect to the daemon over a Unix-domain socket, send it requests, and
  632. read the result---these are remote procedure calls, or RPCs.
  633. The @code{(guix store)} module provides procedures to connect to the
  634. daemon, and to perform RPCs. These are described below.
  635. @deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
  636. Connect to the daemon over the Unix-domain socket at @var{file}. When
  637. @var{reserve-space?} is true, instruct it to reserve a little bit of
  638. extra space on the file system so that the garbage collector can still
  639. operate, should the disk become full. Return a server object.
  640. @var{file} defaults to @var{%default-socket-path}, which is the normal
  641. location given the options that were passed to @command{configure}.
  642. @end deffn
  643. @deffn {Scheme Procedure} close-connection @var{server}
  644. Close the connection to @var{server}.
  645. @end deffn
  646. @defvr {Scheme Variable} current-build-output-port
  647. This variable is bound to a SRFI-39 parameter, which refers to the port
  648. where build and error logs sent by the daemon should be written.
  649. @end defvr
  650. Procedures that make RPCs all take a server object as their first
  651. argument.
  652. @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
  653. Return @code{#t} when @var{path} is a valid store path.
  654. @end deffn
  655. @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} @var{references}
  656. Add @var{text} under file @var{name} in the store, and return its store
  657. path. @var{references} is the list of store paths referred to by the
  658. resulting store path.
  659. @end deffn
  660. @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
  661. Build @var{derivations} (a list of derivation paths), and return when
  662. the worker is done building them. Return @code{#t} on success.
  663. @end deffn
  664. @c FIXME
  665. @i{This section is currently incomplete.}
  666. @node Derivations
  667. @section Derivations
  668. @cindex derivations
  669. Low-level build actions and the environment in which they are performed
  670. are represented by @dfn{derivations}. A derivation contain the
  671. following pieces of information:
  672. @itemize
  673. @item
  674. The outputs of the derivation---derivations produce at least one file or
  675. directory in the store, but may produce more.
  676. @item
  677. The inputs of the derivations, which may be other derivations or plain
  678. files in the store (patches, build scripts, etc.)
  679. @item
  680. The system type targeted by the derivation---e.g., @code{x86_64-linux}.
  681. @item
  682. The file name of a build script in the store, along with the arguments
  683. to be passed.
  684. @item
  685. A list of environment variables to be defined.
  686. @end itemize
  687. @cindex derivation path
  688. Derivations allow clients of the daemon to communicate build actions to
  689. the store. They exist in two forms: as an in-memory representation,
  690. both on the client- and daemon-side, and as files in the store whose
  691. name end in @code{.drv}---these files are referred to as @dfn{derivation
  692. paths}. Derivations paths can be passed to the @code{build-derivations}
  693. procedure to perform the build actions they prescribe (@pxref{The
  694. Store}).
  695. The @code{(guix derivations)} module provides a representation of
  696. derivations as Scheme objects, along with procedures to create and
  697. otherwise manipulate derivations. The lowest-level primitive to create
  698. a derivation is the @code{derivation} procedure:
  699. @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{system} @var{builder} @var{args} @var{env-vars} @var{inputs} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:hash-mode #f]
  700. Build a derivation with the given arguments. Return the resulting store
  701. path and @code{<derivation>} object.
  702. When @var{hash}, @var{hash-algo}, and @var{hash-mode} are given, a
  703. @dfn{fixed-output derivation} is created---i.e., one whose result is
  704. known in advance, such as a file download.
  705. @end deffn
  706. @noindent
  707. Here's an example with a shell script as its builder, assuming
  708. @var{store} is an open connection to the daemon, and @var{bash} points
  709. to a Bash executable in the store:
  710. @lisp
  711. (use-modules (guix utils)
  712. (guix store)
  713. (guix derivations))
  714. (call-with-values
  715. (lambda ()
  716. (let ((builder ; add the Bash script to the store
  717. (add-text-to-store store "my-builder.sh"
  718. "echo hello world > $out\n" '())))
  719. (derivation store "foo" (%current-system)
  720. bash `("-e" ,builder)
  721. '(("HOME" . "/homeless")) '())))
  722. list)
  723. @result{} ("/nix/store/@dots{}-foo.drv" #<<derivation> @dots{}>)
  724. @end lisp
  725. As can be guessed, this primitive is cumbersome to use directly. An
  726. improved variant is @code{build-expression->derivation}, which allows
  727. the caller to directly pass a Guile expression as the build script:
  728. @deffn {Scheme Procedure} build-expression->derivation @var{store} @var{name} @var{system} @var{exp} @var{inputs} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:env-vars '()] [#:modules '()] [#:guile-for-build #f]
  729. Return a derivation that executes Scheme expression @var{exp} as a
  730. builder for derivation @var{name}. @var{inputs} must be a list of
  731. @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
  732. @code{"out"} is assumed. @var{modules} is a list of names of Guile
  733. modules from the current search path to be copied in the store,
  734. compiled, and made available in the load path during the execution of
  735. @var{exp}---e.g., @code{((guix build utils) (guix build
  736. gnu-build-system))}.
  737. @var{exp} is evaluated in an environment where @code{%outputs} is bound
  738. to a list of output/path pairs, and where @code{%build-inputs} is bound
  739. to a list of string/output-path pairs made from @var{inputs}.
  740. Optionally, @var{env-vars} is a list of string pairs specifying the name
  741. and value of environment variables visible to the builder. The builder
  742. terminates by passing the result of @var{exp} to @code{exit}; thus, when
  743. @var{exp} returns @code{#f}, the build is considered to have failed.
  744. @var{exp} is built using @var{guile-for-build} (a derivation). When
  745. @var{guile-for-build} is omitted or is @code{#f}, the value of the
  746. @code{%guile-for-build} fluid is used instead.
  747. @end deffn
  748. @noindent
  749. Here's an example of a single-output derivation that creates a directory
  750. containing one file:
  751. @lisp
  752. (let ((builder '(let ((out (assoc-ref %outputs "out")))
  753. (mkdir out) ; create /nix/store/@dots{}-goo
  754. (call-with-output-file (string-append out "/test")
  755. (lambda (p)
  756. (display '(hello guix) p))))))
  757. (build-expression->derivation store "goo" (%current-system)
  758. builder '()))
  759. @result{} "/nix/store/@dots{}-goo.drv"
  760. @result{} #<<derivation> @dots{}>
  761. @end lisp
  762. @cindex strata of code
  763. Remember that the build expression passed to
  764. @code{build-expression->derivation} is run by a separate Guile process
  765. than the one that calls @code{build-expression->derivation}: it is run
  766. by a Guile process launched by the daemon, typically in a chroot. So,
  767. while there is a single language for both the @dfn{host} and the build
  768. side, there are really two @dfn{strata} of code: the host-side, and the
  769. build-side code@footnote{The term @dfn{stratum} in this context was
  770. coined by Manuel Serrano et al. in the context of their work on Hop.}.
  771. This distinction is important to keep in mind, notably when using
  772. higher-level constructs such as @var{gnu-build-system} (@pxref{Defining
  773. Packages}). For this reason, Guix modules that are meant to be used in
  774. the build stratum are kept in the @code{(guix build @dots{})} name
  775. space.
  776. @c *********************************************************************
  777. @node Utilities
  778. @chapter Utilities
  779. @menu
  780. * Invoking guix-build:: Building packages from the command line.
  781. @end menu
  782. @node Invoking guix-build
  783. @section Invoking @command{guix-build}
  784. The @command{guix-build} command builds packages or derivations and
  785. their dependencies, and prints the resulting store paths. It is mainly
  786. useful for distribution developers. The general syntax is:
  787. @example
  788. guix-build @var{options} @var{package-or-derivation}@dots{}
  789. @end example
  790. @var{package-or-derivation} may be either the name of a package found in
  791. the software distribution such as @code{coreutils}, or a derivation such
  792. as @file{/nix/store/xxx-coreutils-8.19.drv}. Alternatively, the
  793. @code{--expression} option may be used to specify a Scheme expression
  794. that evaluates to a package; this is useful when disambiguation among
  795. several same-named packages or package variants is needed.
  796. The @var{options} may be zero or more of the following:
  797. @table @code
  798. @item --expression=@var{expr}
  799. @itemx -e @var{expr}
  800. Build the package @var{expr} evaluates to.
  801. For example, @var{expr} may be @code{(@@ (distro packages guile)
  802. guile-1.8)}, which unambiguously designates this specific variant of
  803. version 1.8 of Guile.
  804. @item --source
  805. @itemx -S
  806. Build the packages' source derivations, rather than the packages
  807. themselves.
  808. For instance, @code{guix-build -S gcc} returns something like
  809. @file{/nix/store/xxx-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
  810. @item --system=@var{system}
  811. @itemx -s @var{system}
  812. Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
  813. the host's system type.
  814. An example use of this is on Linux-based systems, which can emulate
  815. different personalities. For instance, passing
  816. @code{--system=i686-linux} on an @code{x86_64-linux} system allows users
  817. to build packages in a complete 32-bit environment.
  818. @item --derivations
  819. @itemx -d
  820. Return the derivation paths, not the output paths, of the given
  821. packages.
  822. @item --keep-failed
  823. @itemx -K
  824. Keep the build tree of failed builds. Thus, if a build fail, its build
  825. tree is kept under @file{/tmp}, in a directory whose name is shown at
  826. the end of the build log. This is useful when debugging build issues.
  827. @item --dry-run
  828. @itemx -n
  829. Do not build the derivations.
  830. @item --no-substitutes
  831. Build instead of resorting to pre-built substitutes.
  832. @item --cores=@var{n}
  833. @itemx -c @var{n}
  834. Allow the use of up to @var{n} CPU cores for the build. The special
  835. value @code{0} means to use as many CPU cores as available.
  836. @item --root=@var{file}
  837. @itemx -r @var{file}
  838. Make @var{file} a symlink to the result, and register it as a garbage
  839. collector root.
  840. @item --verbosity=@var{level}
  841. Use the given verbosity level. @var{level} must be an integer between 0
  842. and 5; higher means more verbose output. Setting a level of 4 or more
  843. may be helpful when debugging setup issues with the build daemon.
  844. @end table
  845. Behind the scenes, @command{guix-build} is essentially an interface to
  846. the @code{package-derivation} procedure of the @code{(guix packages)}
  847. module, and to the @code{build-derivations} procedure of the @code{(guix
  848. store)} module.
  849. @c *********************************************************************
  850. @node Acknowledgments
  851. @chapter Acknowledgments
  852. Guix is based on the Nix package manager, which was designed and
  853. implemented by Eelco Dolstra. Nix pioneered functional package
  854. management, and promoted unprecedented features, such as transactional
  855. package upgrades and rollbacks, per-user profiles, and referentially
  856. transparent build processes. Without this work, Guix would not exist.
  857. The Nix-based software distributions, Nixpkgs and NixOS, have also been
  858. an inspiration for Guix.
  859. @c *********************************************************************
  860. @node GNU Free Documentation License
  861. @appendix GNU Free Documentation License
  862. @include fdl-1.3.texi
  863. @c *********************************************************************
  864. @node Concept Index
  865. @unnumbered Concept Index
  866. @printindex cp
  867. @node Function Index
  868. @unnumbered Function Index
  869. @printindex fn
  870. @bye
  871. @c Local Variables:
  872. @c ispell-local-dictionary: "american";
  873. @c End: