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.

1947 lines
77 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. @author Andreas Enge
  23. @author Nikita Karetnikov
  24. @page
  25. @vskip 0pt plus 1filll
  26. Edition @value{EDITION} @*
  27. @value{UPDATED} @*
  28. Copyright @copyright{} @value{YEARS} Ludovic Court@`es, Andreas Enge, Nikita Karetnikov
  29. @quotation
  30. Permission is granted to copy, distribute and/or modify this document
  31. under the terms of the GNU Free Documentation License, Version 1.3 or
  32. any later version published by the Free Software Foundation; with no
  33. Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
  34. copy of the license is included in the section entitled ``GNU Free
  35. Documentation License''.
  36. @end quotation
  37. @end titlepage
  38. @copying
  39. This manual documents GNU Guix version @value{VERSION}.
  40. Copyright @copyright{} @value{YEARS} Ludovic Courtès
  41. Permission is granted to copy, distribute and/or modify this document
  42. under the terms of the GNU Free Documentation License, Version 1.3 or
  43. any later version published by the Free Software Foundation; with no
  44. Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
  45. copy of the license is included in the section entitled ``GNU Free
  46. Documentation License.''
  47. @end copying
  48. @contents
  49. @c *********************************************************************
  50. @node Top
  51. @top GNU Guix
  52. This document describes GNU Guix version @value{VERSION}, a functional
  53. package management tool written for the GNU system.
  54. @menu
  55. * Introduction:: What is Guix about?
  56. * Installation:: Installing Guix.
  57. * Package Management:: Package installation, upgrade, etc.
  58. * Programming Interface:: Using Guix in Scheme.
  59. * Utilities:: Package management commands.
  60. * GNU Distribution:: Software for your friendly GNU system.
  61. * Contributing:: Your help needed!
  62. * Acknowledgments:: Thanks!
  63. * GNU Free Documentation License:: The license of this manual.
  64. * Concept Index:: Concepts.
  65. * Function Index:: Functions.
  66. @end menu
  67. @c *********************************************************************
  68. @node Introduction
  69. @chapter Introduction
  70. GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
  71. using the international phonetic alphabet (IPA).} is a functional
  72. package management tool for the GNU system. Package management consists
  73. of all activities that relate to building packages from sources,
  74. honoring their build-time and run-time dependencies,
  75. installing packages in user environments, upgrading installed packages
  76. to new versions or rolling back to a previous set, removing unused
  77. software packages, etc.
  78. @cindex functional package management
  79. The term @dfn{functional} refers to a specific package management
  80. discipline. In Guix, the package build and installation process is seen
  81. as a function, in the mathematical sense. That function takes inputs,
  82. such as build scripts, a compiler, and libraries, and
  83. returns an installed package. As a pure function, its result depends
  84. solely on its inputs---for instance, it cannot refer to software or
  85. scripts that were not explicitly passed as inputs. A build function
  86. always produces the same result when passed a given set of inputs. It
  87. cannot alter the system's environment in
  88. any way; for instance, it cannot create, modify, or delete files outside
  89. of its build and installation directories. This is achieved by running
  90. build processes in isolated environments (or @dfn{chroots}), where only their
  91. explicit inputs are visible.
  92. @cindex store
  93. The result of package build functions is @dfn{cached} in the file
  94. system, in a special directory called @dfn{the store} (@pxref{The
  95. Store}). Each package is installed in a directory of its own, in the
  96. store---by default under @file{/nix/store}. The directory name contains
  97. a hash of all the inputs used to build that package; thus, changing an
  98. input yields a different directory name.
  99. This approach is the foundation of Guix's salient features: support for
  100. transactional package upgrade and rollback, per-user installation, and
  101. garbage collection of packages (@pxref{Features}).
  102. Guix has a command-line interface, which allows users to build, install,
  103. upgrade, and remove packages, as well as a Scheme programming interface.
  104. Last but not least, Guix is used to build a distribution of the GNU
  105. system, with many GNU and non-GNU free software packages. @xref{GNU
  106. Distribution}.
  107. @c *********************************************************************
  108. @node Installation
  109. @chapter Installation
  110. GNU Guix is available for download from its website at
  111. @url{http://www.gnu.org/software/guix/}. This section describes the
  112. software requirements of Guix, as well as how to install it and get
  113. ready to use it.
  114. The build procedure for Guix is the same as for other GNU software, and
  115. is not covered here. Please see the files @file{README} and
  116. @file{INSTALL} in the Guix source tree for additional details.
  117. @menu
  118. * Requirements:: Software needed to build and run Guix.
  119. * Setting Up the Daemon:: Preparing the build daemon's environment.
  120. * Invoking guix-daemon:: Running the build daemon.
  121. @end menu
  122. @node Requirements
  123. @section Requirements
  124. GNU Guix depends on the following packages:
  125. @itemize
  126. @item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.5 or later;
  127. @item @url{http://gnupg.org/, GNU libgcrypt}
  128. @end itemize
  129. Unless @code{--disable-daemon} was passed to @command{configure}, the
  130. following packages are also needed:
  131. @itemize
  132. @item @url{http://sqlite.org, SQLite 3}
  133. @item @url{http://www.bzip.org, libbz2}
  134. @item @url{http://gcc.gnu.org, GCC's g++}
  135. @end itemize
  136. When a working installation of @url{http://nixos.org/nix/, the Nix package
  137. manager} is available, you
  138. can instead configure Guix with @code{--disable-daemon}. In that case,
  139. 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 stores metadata 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 not required if
  148. your goal is to share the store with 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. @c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
  180. @c for why `-G' is needed.
  181. @example
  182. # groupadd guix-builder
  183. # for i in `seq 1 10`;
  184. do
  185. useradd -g guix-builder -G guix-builder \
  186. -d /var/empty -s `which nologin` \
  187. -c "Guix build user $i" guix-builder$i;
  188. done
  189. @end example
  190. @noindent
  191. The @code{guix-daemon} program may then be run as @code{root} with:
  192. @example
  193. # guix-daemon --build-users-group=guix-builder
  194. @end example
  195. @noindent
  196. This way, the daemon starts build processes in a chroot, under one of
  197. the @code{guix-builder} users. On GNU/Linux, by default, the chroot
  198. environment contains nothing but the @code{/dev} and @code{/proc}
  199. directories@footnote{On some systems @code{/dev/shm}, which supports
  200. shared memory, is a symlink to another directory such as
  201. @code{/run/shm}, that is @emph{not} is the chroot. When that is the
  202. case, shared memory support is unavailable in the chroot environment.
  203. The workaround is to make sure that @file{/dev/shm} is directly a
  204. @code{tmpfs} mount point.}.
  205. Guix may also be used in a single-user setup, with @command{guix-daemon}
  206. running as an unprivileged user. However, to maximize non-interference
  207. of build processes, the daemon still needs to perform certain operations
  208. that are restricted to @code{root} on GNU/Linux: it should be able to
  209. run build processes in a chroot, and to run them under different UIDs.
  210. To that end, the @command{nix-setuid-helper} program is provided; it is
  211. a small C program (less than 300 lines) that, if it is made setuid
  212. @code{root}, can be executed by the daemon to perform these operations
  213. on its behalf. The @code{root}-owned @file{/etc/nix-setuid.conf} file
  214. is read by @command{nix-setuid-helper}; it should contain exactly two
  215. words: the user name under which the authorized @command{guix-daemon}
  216. runs, and the name of the build users group.
  217. If you are installing Guix as an unprivileged user and do not have the
  218. ability to make @file{nix-setuid-helper} setuid-@code{root}, it is still
  219. possible to run @command{guix-daemon}. However, build processes will
  220. not be isolated from one another, and not from the rest of the system.
  221. Thus, build processes may interfere with each other, and may access
  222. programs, libraries, and other files available on the system---making it
  223. much harder to view them as @emph{pure} functions.
  224. @node Invoking guix-daemon
  225. @section Invoking @command{guix-daemon}
  226. The @command{guix-daemon} program implements all the functionality to
  227. access the store. This includes launching build processes, running the
  228. garbage collector, querying the availability of a build result, etc. It
  229. is normally run as @code{root} like this:
  230. @example
  231. # guix-daemon --build-users-group=guix-builder
  232. @end example
  233. @noindent
  234. For details on how to set it up, @ref{Setting Up the Daemon}.
  235. By default, @command{guix-daemon} launches build processes under
  236. different UIDs, taken from the build group specified with
  237. @code{--build-users-group}. In addition, each build process is run in a
  238. chroot environment that only contains the subset of the store that the
  239. build process depends on, as specified by its derivation
  240. (@pxref{Programming Interface, derivation}), plus a set of specific
  241. system directories. By default, the latter contains @file{/dev} and
  242. @file{/dev/pts}.
  243. The following command-line options are supported:
  244. @table @code
  245. @item --build-users-group=@var{group}
  246. Take users from @var{group} to run build processes (@pxref{Setting Up
  247. the Daemon, build users}).
  248. @item --no-substitutes
  249. Do not use substitutes for build products. That is, always build things
  250. locally instead of allowing downloads of pre-built binaries.
  251. @item --cache-failures
  252. Cache build failures. By default, only successful builds are cached.
  253. @item --cores=@var{n}
  254. @itemx -c @var{n}
  255. Use @var{n} CPU cores to build each derivation; @code{0} means as many
  256. as available.
  257. The default value is @code{1}, but it may be overridden by clients, such
  258. as the @code{--cores} option of @command{guix build} (@pxref{Invoking
  259. guix build}).
  260. The effect is to define the @code{NIX_BUILD_CORES} environment variable
  261. in the build process, which can then use it to exploit internal
  262. parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
  263. @item --max-jobs=@var{n}
  264. @itemx -M @var{n}
  265. Allow at most @var{n} build jobs in parallel. The default value is
  266. @code{1}.
  267. @item --debug
  268. Produce debugging output.
  269. This is useful to debug daemon start-up issues, but then it may be
  270. overridden by clients, for example the @code{--verbosity} option of
  271. @command{guix build} (@pxref{Invoking guix build}).
  272. @item --chroot-directory=@var{dir}
  273. Add @var{dir} to the build chroot.
  274. Doing this may change the result of build processes---for instance if
  275. they use optional dependencies found in @var{dir} when it is available,
  276. and not otherwise. For that reason, it is not recommended to do so.
  277. Instead, make sure that each derivation declares all the inputs that it
  278. needs.
  279. @item --disable-chroot
  280. Disable chroot builds.
  281. Using this option is not recommended since, again, it would allow build
  282. processes to gain access to undeclared dependencies.
  283. @item --disable-log-compression
  284. Disable compression of the build logs.
  285. Unless @code{--lose-logs} is used, all the build logs are kept in the
  286. @var{localstatedir}. To save space, the daemon automatically compresses
  287. them with bzip2 by default. This option disables that.
  288. @item --disable-store-optimization
  289. Disable automatic file ``deduplication'' in the store.
  290. By default, files added to the store are automatically ``deduplicated'':
  291. if a newly added file is identical as another one found in the store,
  292. the daemon makes the new file a hard link to the other file. This
  293. slightly increases the input/output load at the end of a build process.
  294. This option disables this.
  295. @item --impersonate-linux-2.6
  296. On Linux-based systems, impersonate Linux 2.6. This means that the
  297. kernel's @code{uname} system call will report 2.6 as the release number.
  298. This might be helpful to build programs that (usually wrongfully) depend
  299. on the kernel version number.
  300. @item --lose-logs
  301. Do not keep build logs. By default they are kept under
  302. @code{@var{localstatedir}/nix/log}.
  303. @item --system=@var{system}
  304. Assume @var{system} as the current system type. By default it is the
  305. architecture/kernel pair found at configure time, such as
  306. @code{x86_64-linux}.
  307. @item --listen=@var{socket}
  308. Listen for connections on @var{socket}, the file name of a Unix-domain
  309. socket. The default socket is
  310. @file{@var{localstatedir}/daemon-socket/socket}. This option is only
  311. useful in exceptional circumstances, such as if you need to run several
  312. daemons on the same machine.
  313. @end table
  314. @c *********************************************************************
  315. @node Package Management
  316. @chapter Package Management
  317. The purpose of GNU Guix is to allow users to easily install, upgrade, and
  318. remove software packages, without having to know about their build
  319. procedure or dependencies. Guix also goes beyond this obvious set of
  320. features.
  321. This chapter describes the main features of Guix, as well as the package
  322. management tools it provides.
  323. @menu
  324. * Features:: How Guix will make your life brighter.
  325. * Invoking guix package:: Package installation, removal, etc.
  326. * Packages with Multiple Outputs:: Single source package, multiple outputs.
  327. * Invoking guix gc:: Running the garbage collector.
  328. * Invoking guix pull:: Fetching the latest Guix and distribution.
  329. @end menu
  330. @node Features
  331. @section Features
  332. When using Guix, each package ends up in the @dfn{package store}, in its
  333. own directory---something that resembles
  334. @file{/nix/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
  335. Instead of referring to these directories, users have their own
  336. @dfn{profile}, which points to the packages that they actually want to
  337. use. These profiles are stored within each user's home directory, at
  338. @code{$HOME/.guix-profile}.
  339. For example, @code{alice} installs GCC 4.7.2. As a result,
  340. @file{/home/alice/.guix-profile/bin/gcc} points to
  341. @file{/nix/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
  342. @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
  343. simply continues to point to
  344. @file{/nix/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
  345. coexist on the same system without any interference.
  346. The @command{guix package} command is the central tool to manage
  347. packages (@pxref{Invoking guix package}). It operates on those per-user
  348. profiles, and can be used @emph{with normal user privileges}.
  349. The command provides the obvious install, remove, and upgrade
  350. operations. Each invocation is actually a @emph{transaction}: either
  351. the specified operation succeeds, or nothing happens. Thus, if the
  352. @command{guix package} process is terminated during the transaction,
  353. or if a power outage occurs during the transaction, then the user's
  354. profile remains in its previous state, and remains usable.
  355. In addition, any package transaction may be @emph{rolled back}. So, if,
  356. for example, an upgrade installs a new version of a package that turns
  357. out to have a serious bug, users may roll back to the previous instance
  358. of their profile, which was known to work well.
  359. All those packages in the package store may be @emph{garbage-collected}.
  360. Guix can determine which packages are still referenced by the user
  361. profiles, and remove those that are provably no longer referenced
  362. (@pxref{Invoking guix gc}). Users may also explicitly remove old
  363. generations of their profile so that the packages they refer to can be
  364. collected.
  365. Finally, Guix takes a @dfn{purely functional} approach to package
  366. management, as described in the introduction (@pxref{Introduction}).
  367. Each @file{/nix/store} package directory name contains a hash of all the
  368. inputs that were used to build that package---compiler, libraries, build
  369. scripts, etc. This direct correspondence allows users to make sure a
  370. given package installation matches the current state of their
  371. distribution, and helps maximize @dfn{reproducibility}.
  372. This foundation allows Guix to support @dfn{transparent binary/source
  373. deployment}. When a pre-built binary for a @file{/nix/store} path is
  374. available from an external source, Guix just downloads it; otherwise, it
  375. builds the package from source, locally.
  376. @node Invoking guix package
  377. @section Invoking @command{guix package}
  378. The @command{guix package} command is the tool that allows users to
  379. install, upgrade, and remove packages, as well as rolling back to
  380. previous configurations. It operates only on the user's own profile,
  381. and works with normal user privileges (@pxref{Features}). Its syntax
  382. is:
  383. @example
  384. guix package @var{options}
  385. @end example
  386. Primarily, @var{options} specifies the operations to be performed during
  387. the transaction. Upon completion, a new profile is created, but
  388. previous generations of the profile remain available, should the user
  389. want to roll back.
  390. For each user, a symlink to the user's default profile is automatically
  391. created in @file{$HOME/.guix-profile}. This symlink always points to the
  392. current generation of the user's default profile. Thus, users can add
  393. @file{$HOME/.guix-profile/bin} to their @code{PATH} environment
  394. variable, and so on.
  395. In a multi-user setup, user profiles must be stored in a place
  396. registered as a @dfn{garbage-collector root}, which
  397. @file{$HOME/.guix-profile} points to (@pxref{Invoking guix gc}). That
  398. directory is normally
  399. @code{@var{localstatedir}/profiles/per-user/@var{user}}, where
  400. @var{localstatedir} is the value passed to @code{configure} as
  401. @code{--localstatedir}, and @var{user} is the user name. It must be
  402. created by @code{root}, with @var{user} as the owner. When it does not
  403. exist, or is not owned by @var{user}, @command{guix package} emits an
  404. error about it.
  405. The @var{options} can be among the following:
  406. @table @code
  407. @item --install=@var{package}
  408. @itemx -i @var{package}
  409. Install @var{package}.
  410. @var{package} may specify either a simple package name, such as
  411. @code{guile}, or a package name followed by a hyphen and version number,
  412. such as @code{guile-1.8.8}. If no version number is specified, the
  413. newest available version will be selected. In addition, @var{package}
  414. may contain a colon, followed by the name of one of the outputs of the
  415. package, as in @code{gcc:doc} or @code{binutils-2.22:lib}
  416. (@pxref{Packages with Multiple Outputs}).
  417. @cindex propagated inputs
  418. Sometimes packages have @dfn{propagated inputs}: these are dependencies
  419. that automatically get installed along with the required package.
  420. An example is the GNU MPC library: its C header files refer to those of
  421. the GNU MPFR library, which in turn refer to those of the GMP library.
  422. Thus, when installing MPC, the MPFR and GMP libraries also get installed
  423. in the profile; removing MPC also removes MPFR and GMP---unless they had
  424. also been explicitly installed independently.
  425. Besides, packages sometime rely on the definition of environment
  426. variables for their search paths (see explanation of
  427. @code{--search-paths} below.) Any missing or possibly incorrect
  428. environment variable definitions are reported here.
  429. @c XXX: keep me up-to-date
  430. Finally, when installing a GNU package, the tool reports the
  431. availability of a newer upstream version. In the future, it may provide
  432. the option of installing directly from the upstream version, even if
  433. that version is not yet in the distribution.
  434. @item --install-from-expression=@var{exp}
  435. @itemx -e @var{exp}
  436. Install the package @var{exp} evaluates to.
  437. @var{exp} must be a Scheme expression that evaluates to a
  438. @code{<package>} object. This option is notably useful to disambiguate
  439. between same-named variants of a package, with expressions such as
  440. @code{(@@ (gnu packages base) guile-final)}.
  441. Note that this option installs the first output of the specified
  442. package, which may be insufficient when needing a specific output of a
  443. multiple-output package.
  444. @item --remove=@var{package}
  445. @itemx -r @var{package}
  446. Remove @var{package}.
  447. @item --upgrade[=@var{regexp}]
  448. @itemx -u [@var{regexp}]
  449. Upgrade all the installed packages. When @var{regexp} is specified, upgrade
  450. only installed packages whose name matches @var{regexp}.
  451. Note that this upgrades package to the latest version of packages found
  452. in the distribution currently installed. To update your distribution,
  453. you should regularly run @command{guix pull} (@pxref{Invoking guix
  454. pull}).
  455. @item --roll-back
  456. Roll back to the previous @dfn{generation} of the profile---i.e., undo
  457. the last transaction.
  458. When combined with options such as @code{--install}, roll back occurs
  459. before any other actions.
  460. When rolling back from the first generation that actually contains
  461. installed packages, the profile is made to point to the @dfn{empty
  462. profile}, also known as @dfn{profile zero}---i.e., it contains no files
  463. apart from its own meta-data.
  464. Installing, removing, or upgrading packages from a generation that has
  465. been rolled back to overwrites previous future generations. Thus, the
  466. history of a profile's generations is always linear.
  467. @item --search-paths
  468. @cindex search paths
  469. Report environment variable definitions, in Bash syntax, that may be
  470. needed in order to use the set of installed packages. These environment
  471. variables are used to specify @dfn{search paths} for files used by some
  472. of the installed packages.
  473. For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
  474. environment variables to be defined so it can look for headers and
  475. libraries in the user's profile (@pxref{Environment Variables,,, gcc,
  476. Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
  477. library are installed in the profile, then @code{--search-paths} will
  478. suggest setting these variables to @code{@var{profile}/include} and
  479. @code{@var{profile}/lib}, respectively.
  480. @item --profile=@var{profile}
  481. @itemx -p @var{profile}
  482. Use @var{profile} instead of the user's default profile.
  483. @item --dry-run
  484. @itemx -n
  485. Show what would be done without actually doing it.
  486. @item --fallback
  487. When substituting a pre-built binary fails, fall back to building
  488. packages locally.
  489. @item --no-substitutes
  490. @itemx --max-silent-time=@var{seconds}
  491. Same as for @command{guix build} (@pxref{Invoking guix build}).
  492. @item --verbose
  493. Produce verbose output. In particular, emit the environment's build log
  494. on the standard error port.
  495. @item --bootstrap
  496. Use the bootstrap Guile to build the profile. This option is only
  497. useful to distribution developers.
  498. @end table
  499. In addition to these actions @command{guix package} supports the
  500. following options to query the current state of a profile, or the
  501. availability of packages:
  502. @table @option
  503. @item --search=@var{regexp}
  504. @itemx -s @var{regexp}
  505. List the available packages whose synopsis or description matches
  506. @var{regexp}. Print all the meta-data of matching packages in
  507. @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
  508. GNU recutils manual}).
  509. This allows specific fields to be extracted using the @command{recsel}
  510. command, for instance:
  511. @example
  512. $ guix package -s malloc | recsel -p name,version
  513. name: glibc
  514. version: 2.17
  515. name: libgc
  516. version: 7.2alpha6
  517. @end example
  518. @item --list-installed[=@var{regexp}]
  519. @itemx -I [@var{regexp}]
  520. List currently installed packages in the specified profile. When
  521. @var{regexp} is specified, list only installed packages whose name
  522. matches @var{regexp}.
  523. For each installed package, print the following items, separated by
  524. tabs: the package name, its version string, the part of the package that
  525. is installed (for instance, @code{out} for the default output,
  526. @code{include} for its headers, etc.), and the path of this package in
  527. the store.
  528. @item --list-available[=@var{regexp}]
  529. @itemx -A [@var{regexp}]
  530. List packages currently available in the software distribution
  531. (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
  532. installed packages whose name matches @var{regexp}.
  533. For each package, print the following items separated by tabs: its name,
  534. its version string, the parts of the package (@pxref{Packages with
  535. Multiple Outputs}), and the source location of its definition.
  536. @end table
  537. @node Packages with Multiple Outputs
  538. @section Packages with Multiple Outputs
  539. @cindex multiple-output packages
  540. @cindex package outputs
  541. Often, packages defined in Guix have a single @dfn{output}---i.e., the
  542. source package leads exactly one directory in the store. When running
  543. @command{guix package -i glibc}, one installs the default output of the
  544. GNU libc package; the default output is called @code{out}, but its name
  545. can be omitted as shown in this command. In this particular case, the
  546. default output of @code{glibc} contains all the C header files, shared
  547. libraries, static libraries, Info documentation, and other supporting
  548. files.
  549. Sometimes it is more appropriate to separate the various types of files
  550. produced from a single source package into separate outputs. For
  551. instance, the GLib C library (used by GTK+ and related packages)
  552. installs more than 20 MiB of reference documentation as HTML pages.
  553. To save space for users who do not need it, the documentation goes to a
  554. separate output, called @code{doc}. To install the main GLib output,
  555. which contains everything but the documentation, one would run:
  556. @example
  557. guix package -i glib
  558. @end example
  559. The command to install its documentation is:
  560. @example
  561. guix package -i glib:doc
  562. @end example
  563. Some packages install programs with different ``dependency footprints''.
  564. For instance, the WordNet package install both command-line tools and
  565. graphical user interfaces (GUIs). The former depend solely on the C
  566. library, whereas the latter depend on Tcl/Tk and the underlying X
  567. libraries. In this case, we leave the command-line tools in the default
  568. output, whereas the GUIs are in a separate output. This allows users
  569. who do not need the GUIs to save space.
  570. There are several such multiple-output packages in the GNU distribution.
  571. Other conventional output names include @code{lib} for libraries and
  572. possibly header files, @code{bin} for stand-alone programs, and
  573. @code{debug} for debugging information (@pxref{Installing Debugging
  574. Files}). The outputs of a packages are listed in the third column of
  575. the output of @command{guix package --list-available} (@pxref{Invoking
  576. guix package}).
  577. @node Invoking guix gc
  578. @section Invoking @command{guix gc}
  579. @cindex garbage collector
  580. Packages that are installed but not used may be @dfn{garbage-collected}.
  581. The @command{guix gc} command allows users to explicitly run the garbage
  582. collector to reclaim space from the @file{/nix/store} directory.
  583. The garbage collector has a set of known @dfn{roots}: any file under
  584. @file{/nix/store} reachable from a root is considered @dfn{live} and
  585. cannot be deleted; any other file is considered @dfn{dead} and may be
  586. deleted. The set of garbage collector roots includes default user
  587. profiles, and may be augmented with @command{guix build --root}, for
  588. example (@pxref{Invoking guix build}).
  589. The @command{guix gc} command has three modes of operation: it can be
  590. used to garbage-collect any dead files (the default), to delete specific
  591. files (the @code{--delete} option), or to print garbage-collector
  592. information. The available options are listed below:
  593. @table @code
  594. @item --collect-garbage[=@var{min}]
  595. @itemx -C [@var{min}]
  596. Collect garbage---i.e., unreachable @file{/nix/store} files and
  597. sub-directories. This is the default operation when no option is
  598. specified.
  599. When @var{min} is given, stop once @var{min} bytes have been collected.
  600. @var{min} may be a number of bytes, or it may include a unit as a
  601. suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes.
  602. When @var{min} is omitted, collect all the garbage.
  603. @item --delete
  604. @itemx -d
  605. Attempt to delete all the store files and directories specified as
  606. arguments. This fails if some of the files are not in the store, or if
  607. they are still live.
  608. @item --list-dead
  609. Show the list of dead files and directories still present in the
  610. store---i.e., files and directories no longer reachable from any root.
  611. @item --list-live
  612. Show the list of live store files and directories.
  613. @end table
  614. In addition, the references among existing store files can be queried:
  615. @table @code
  616. @item --references
  617. @itemx --referrers
  618. List the references (respectively, the referrers) of store files given
  619. as arguments.
  620. @item --requisites
  621. @itemx -R
  622. List the requisites of the store files passed as arguments. Requisites
  623. include the store files themselves, their references, and the references
  624. of these, recursively. In other words, the returned list is the
  625. @dfn{transitive closure} of the store files.
  626. @end table
  627. @node Invoking guix pull
  628. @section Invoking @command{guix pull}
  629. Packages are installed or upgraded to the latest version available in
  630. the distribution currently available on your local machine. To update
  631. that distribution, along with the Guix tools, you must run @command{guix
  632. pull}: the command downloads the latest Guix source code and package
  633. descriptions, and deploys it.
  634. On completion, @command{guix package} will use packages and package
  635. versions from this just-retrieved copy of Guix. Not only that, but all
  636. the Guix commands and Scheme modules will also be taken from that latest
  637. version. New @command{guix} sub-commands added by the update also
  638. become available.
  639. The @command{guix pull} command is usually invoked with no arguments,
  640. but it supports the following options:
  641. @table @code
  642. @item --verbose
  643. Produce verbose output, writing build logs to the standard error output.
  644. @item --bootstrap
  645. Use the bootstrap Guile to build the latest Guix. This option is only
  646. useful to Guix developers.
  647. @end table
  648. @c *********************************************************************
  649. @node Programming Interface
  650. @chapter Programming Interface
  651. GNU Guix provides several Scheme programming interfaces (APIs) to
  652. define, build, and query packages. The first interface allows users to
  653. write high-level package definitions. These definitions refer to
  654. familiar packaging concepts, such as the name and version of a package,
  655. its build system, and its dependencies. These definitions can then be
  656. turned into concrete build actions.
  657. Build actions are performed by the Guix daemon, on behalf of users. In a
  658. standard setup, the daemon has write access to the store---the
  659. @file{/nix/store} directory---whereas users do not. The recommended
  660. setup also has the daemon perform builds in chroots, under a specific
  661. build users, to minimize interference with the rest of the system.
  662. @cindex derivation
  663. Lower-level APIs are available to interact with the daemon and the
  664. store. To instruct the daemon to perform a build action, users actually
  665. provide it with a @dfn{derivation}. A derivation is a low-level
  666. representation of the build actions to be taken, and the environment in
  667. which they should occur---derivations are to package definitions what
  668. assembly is to C programs.
  669. This chapter describes all these APIs in turn, starting from high-level
  670. package definitions.
  671. @menu
  672. * Defining Packages:: Defining new packages.
  673. * The Store:: Manipulating the package store.
  674. * Derivations:: Low-level interface to package derivations.
  675. @end menu
  676. @node Defining Packages
  677. @section Defining Packages
  678. The high-level interface to package definitions is implemented in the
  679. @code{(guix packages)} and @code{(guix build-system)} modules. As an
  680. example, the package definition, or @dfn{recipe}, for the GNU Hello
  681. package looks like this:
  682. @example
  683. (use-modules (guix packages)
  684. (guix download)
  685. (guix build-system gnu)
  686. (guix licenses))
  687. (define hello
  688. (package
  689. (name "hello")
  690. (version "2.8")
  691. (source (origin
  692. (method url-fetch)
  693. (uri (string-append "mirror://gnu/hello/hello-" version
  694. ".tar.gz"))
  695. (sha256
  696. (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
  697. (build-system gnu-build-system)
  698. (inputs `(("gawk" ,gawk)))
  699. (synopsis "GNU Hello")
  700. (description "Yeah...")
  701. (home-page "http://www.gnu.org/software/hello/")
  702. (license gpl3+)))
  703. @end example
  704. @noindent
  705. Without being a Scheme expert, the reader may have guessed the meaning
  706. of the various fields here. This expression binds variable @var{hello}
  707. to a @code{<package>} object, which is essentially a record
  708. (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
  709. This package object can be inspected using procedures found in the
  710. @code{(guix packages)} module; for instance, @code{(package-name hello)}
  711. returns---surprise!---@code{"hello"}.
  712. There are a few points worth noting in the above package definition:
  713. @itemize
  714. @item
  715. The @code{source} field of the package is an @code{<origin>} object.
  716. Here, the @code{url-fetch} method from @code{(guix download)} is used,
  717. meaning that the source is a file to be downloaded over FTP or HTTP.
  718. The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
  719. the GNU mirrors defined in @code{(guix download)}.
  720. The @code{sha256} field specifies the expected SHA256 hash of the file
  721. being downloaded. It is mandatory, and allows Guix to check the
  722. integrity of the file. The @code{(base32 @dots{})} form introduces the
  723. base32 representation of the hash. You can obtain this information with
  724. @code{guix download} (@pxref{Invoking guix download}) and @code{guix
  725. hash} (@pxref{Invoking guix hash}).
  726. @item
  727. @cindex GNU Build System
  728. The @code{build-system} field is set to @var{gnu-build-system}. The
  729. @var{gnu-build-system} variable is defined in the @code{(guix
  730. build-system gnu)} module, and is bound to a @code{<build-system>}
  731. object.
  732. Naturally, @var{gnu-build-system} represents the familiar GNU Build
  733. System, and variants thereof (@pxref{Configuration, configuration and
  734. makefile conventions,, standards, GNU Coding Standards}). In a
  735. nutshell, packages using the GNU Build System may be configured, built,
  736. and installed with the usual @code{./configure && make && make check &&
  737. make install} command sequence. This is what @var{gnu-build-system}
  738. does.
  739. In addition, @var{gnu-build-system} ensures that the ``standard''
  740. environment for GNU packages is available. This includes tools such as
  741. GCC, Coreutils, Bash, Make, Diffutils, and Patch.
  742. @item
  743. The @code{inputs} field specifies inputs to the build process---i.e.,
  744. build-time or run-time dependencies of the package. Here, we define an
  745. input called @code{"gawk"} whose value is that of the @var{gawk}
  746. variable; @var{gawk} is itself bound to a @code{<package>} object.
  747. Note that GCC, Coreutils, Bash, and other essential tools do not need to
  748. be specified as inputs here. Instead, @var{gnu-build-system} takes care
  749. of ensuring that they are present.
  750. However, any other dependencies need to be specified in the
  751. @code{inputs} field. Any dependency not specified here will simply be
  752. unavailable to the build process, possibly leading to a build failure.
  753. @end itemize
  754. There are other fields that package definitions may provide. Of
  755. particular interest is the @code{arguments} field. When specified, it
  756. must be bound to a list of additional arguments to be passed to the
  757. build system. For instance, the above definition could be augmented
  758. with the following field initializer:
  759. @example
  760. (arguments `(#:tests? #f
  761. #:configure-flags '("--enable-silent-rules")))
  762. @end example
  763. @noindent
  764. These are keyword arguments (@pxref{Optional Arguments, keyword
  765. arguments in Guile,, guile, GNU Guile Reference Manual}). They are
  766. passed to @var{gnu-build-system}, which interprets them as meaning ``do
  767. not run @code{make check}'', and ``run @file{configure} with the
  768. @code{--enable-silent-rules} flag''. The value of these keyword
  769. parameters is actually evaluated in the @dfn{build stratum}---i.e., by a
  770. Guile process launched by the daemon (@pxref{Derivations}).
  771. Once a package definition is in place@footnote{Simple package
  772. definitions like the one above may be automatically converted from the
  773. Nixpkgs distribution using the @command{guix import} command.}, the
  774. package may actually be built using the @code{guix build} command-line
  775. tool (@pxref{Invoking guix build}). Eventually, updating the package
  776. definition to a new upstream version can be partly automated by the
  777. @command{guix refresh} command (@pxref{Invoking guix refresh}).
  778. Behind the scenes, a derivation corresponding to the @code{<package>}
  779. object is first computed by the @code{package-derivation} procedure.
  780. That derivation is stored in a @code{.drv} file under @file{/nix/store}.
  781. The build actions it prescribes may then be realized by using the
  782. @code{build-derivations} procedure (@pxref{The Store}).
  783. @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
  784. Return the derivation path and corresponding @code{<derivation>} object
  785. of @var{package} for @var{system} (@pxref{Derivations}).
  786. @var{package} must be a valid @code{<package>} object, and @var{system}
  787. must be a string denoting the target system type---e.g.,
  788. @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
  789. must be a connection to the daemon, which operates on the store
  790. (@pxref{The Store}).
  791. @end deffn
  792. @noindent
  793. @cindex cross-compilation
  794. Similarly, it is possible to compute a derivation that cross-builds a
  795. package for some other system:
  796. @deffn {Scheme Procedure} package-cross-derivation @var{store} @
  797. @var{package} @var{target} [@var{system}]
  798. Return the derivation path and corresponding @code{<derivation>} object
  799. of @var{package} cross-built from @var{system} to @var{target}.
  800. @var{target} must be a valid GNU triplet denoting the target hardware
  801. and operating system, such as @code{"mips64el-linux-gnu"}
  802. (@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
  803. Configure and Build System}).
  804. @end deffn
  805. @node The Store
  806. @section The Store
  807. @cindex store
  808. @cindex store paths
  809. Conceptually, the @dfn{store} is where derivations that have been
  810. successfully built are stored---by default, under @file{/nix/store}.
  811. Sub-directories in the store are referred to as @dfn{store paths}. The
  812. store has an associated database that contains information such has the
  813. store paths referred to by each store path, and the list of @emph{valid}
  814. store paths---paths that result from a successful build.
  815. The store is always accessed by the daemon on behalf of its clients
  816. (@pxref{Invoking guix-daemon}). To manipulate the store, clients
  817. connect to the daemon over a Unix-domain socket, send it requests, and
  818. read the result---these are remote procedure calls, or RPCs.
  819. The @code{(guix store)} module provides procedures to connect to the
  820. daemon, and to perform RPCs. These are described below.
  821. @deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
  822. Connect to the daemon over the Unix-domain socket at @var{file}. When
  823. @var{reserve-space?} is true, instruct it to reserve a little bit of
  824. extra space on the file system so that the garbage collector can still
  825. operate, should the disk become full. Return a server object.
  826. @var{file} defaults to @var{%default-socket-path}, which is the normal
  827. location given the options that were passed to @command{configure}.
  828. @end deffn
  829. @deffn {Scheme Procedure} close-connection @var{server}
  830. Close the connection to @var{server}.
  831. @end deffn
  832. @defvr {Scheme Variable} current-build-output-port
  833. This variable is bound to a SRFI-39 parameter, which refers to the port
  834. where build and error logs sent by the daemon should be written.
  835. @end defvr
  836. Procedures that make RPCs all take a server object as their first
  837. argument.
  838. @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
  839. Return @code{#t} when @var{path} is a valid store path.
  840. @end deffn
  841. @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} @var{references}
  842. Add @var{text} under file @var{name} in the store, and return its store
  843. path. @var{references} is the list of store paths referred to by the
  844. resulting store path.
  845. @end deffn
  846. @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
  847. Build @var{derivations} (a list of derivation paths), and return when
  848. the worker is done building them. Return @code{#t} on success.
  849. @end deffn
  850. @c FIXME
  851. @i{This section is currently incomplete.}
  852. @node Derivations
  853. @section Derivations
  854. @cindex derivations
  855. Low-level build actions and the environment in which they are performed
  856. are represented by @dfn{derivations}. A derivation contain the
  857. following pieces of information:
  858. @itemize
  859. @item
  860. The outputs of the derivation---derivations produce at least one file or
  861. directory in the store, but may produce more.
  862. @item
  863. The inputs of the derivations, which may be other derivations or plain
  864. files in the store (patches, build scripts, etc.)
  865. @item
  866. The system type targeted by the derivation---e.g., @code{x86_64-linux}.
  867. @item
  868. The file name of a build script in the store, along with the arguments
  869. to be passed.
  870. @item
  871. A list of environment variables to be defined.
  872. @end itemize
  873. @cindex derivation path
  874. Derivations allow clients of the daemon to communicate build actions to
  875. the store. They exist in two forms: as an in-memory representation,
  876. both on the client- and daemon-side, and as files in the store whose
  877. name end in @code{.drv}---these files are referred to as @dfn{derivation
  878. paths}. Derivations paths can be passed to the @code{build-derivations}
  879. procedure to perform the build actions they prescribe (@pxref{The
  880. Store}).
  881. The @code{(guix derivations)} module provides a representation of
  882. derivations as Scheme objects, along with procedures to create and
  883. otherwise manipulate derivations. The lowest-level primitive to create
  884. a derivation is the @code{derivation} procedure:
  885. @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:hash-mode #f] [#:inputs '()] [#:env-vars '()] [#:system (%current-system)] [#:references-graphs #f]
  886. Build a derivation with the given arguments. Return the resulting store
  887. path and @code{<derivation>} object.
  888. When @var{hash}, @var{hash-algo}, and @var{hash-mode} are given, a
  889. @dfn{fixed-output derivation} is created---i.e., one whose result is
  890. known in advance, such as a file download.
  891. When @var{references-graphs} is true, it must be a list of file
  892. name/store path pairs. In that case, the reference graph of each store
  893. path is exported in the build environment in the corresponding file, in
  894. a simple text format.
  895. @end deffn
  896. @noindent
  897. Here's an example with a shell script as its builder, assuming
  898. @var{store} is an open connection to the daemon, and @var{bash} points
  899. to a Bash executable in the store:
  900. @lisp
  901. (use-modules (guix utils)
  902. (guix store)
  903. (guix derivations))
  904. (call-with-values
  905. (lambda ()
  906. (let ((builder ; add the Bash script to the store
  907. (add-text-to-store store "my-builder.sh"
  908. "echo hello world > $out\n" '())))
  909. (derivation store "foo"
  910. bash `("-e" ,builder)
  911. #:env-vars '(("HOME" . "/homeless")))))
  912. list)
  913. @result{} ("/nix/store/@dots{}-foo.drv" #<<derivation> @dots{}>)
  914. @end lisp
  915. As can be guessed, this primitive is cumbersome to use directly. An
  916. improved variant is @code{build-expression->derivation}, which allows
  917. the caller to directly pass a Guile expression as the build script:
  918. @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 '()] [#:references-graphs #f] [#:guile-for-build #f]
  919. Return a derivation that executes Scheme expression @var{exp} as a
  920. builder for derivation @var{name}. @var{inputs} must be a list of
  921. @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
  922. @code{"out"} is assumed. @var{modules} is a list of names of Guile
  923. modules from the current search path to be copied in the store,
  924. compiled, and made available in the load path during the execution of
  925. @var{exp}---e.g., @code{((guix build utils) (guix build
  926. gnu-build-system))}.
  927. @var{exp} is evaluated in an environment where @code{%outputs} is bound
  928. to a list of output/path pairs, and where @code{%build-inputs} is bound
  929. to a list of string/output-path pairs made from @var{inputs}.
  930. Optionally, @var{env-vars} is a list of string pairs specifying the name
  931. and value of environment variables visible to the builder. The builder
  932. terminates by passing the result of @var{exp} to @code{exit}; thus, when
  933. @var{exp} returns @code{#f}, the build is considered to have failed.
  934. @var{exp} is built using @var{guile-for-build} (a derivation). When
  935. @var{guile-for-build} is omitted or is @code{#f}, the value of the
  936. @code{%guile-for-build} fluid is used instead.
  937. See the @code{derivation} procedure for the meaning of @var{references-graphs}.
  938. @end deffn
  939. @noindent
  940. Here's an example of a single-output derivation that creates a directory
  941. containing one file:
  942. @lisp
  943. (let ((builder '(let ((out (assoc-ref %outputs "out")))
  944. (mkdir out) ; create /nix/store/@dots{}-goo
  945. (call-with-output-file (string-append out "/test")
  946. (lambda (p)
  947. (display '(hello guix) p))))))
  948. (build-expression->derivation store "goo" (%current-system)
  949. builder '()))
  950. @result{} "/nix/store/@dots{}-goo.drv"
  951. @result{} #<<derivation> @dots{}>
  952. @end lisp
  953. @cindex strata of code
  954. Remember that the build expression passed to
  955. @code{build-expression->derivation} is run by a separate Guile process
  956. than the one that calls @code{build-expression->derivation}: it is run
  957. by a Guile process launched by the daemon, typically in a chroot. So,
  958. while there is a single language for both the @dfn{host} and the build
  959. side, there are really two @dfn{strata} of code: the host-side, and the
  960. build-side code@footnote{The term @dfn{stratum} in this context was
  961. coined by Manuel Serrano et al. in the context of their work on Hop.}.
  962. This distinction is important to keep in mind, notably when using
  963. higher-level constructs such as @var{gnu-build-system} (@pxref{Defining
  964. Packages}). For this reason, Guix modules that are meant to be used in
  965. the build stratum are kept in the @code{(guix build @dots{})} name
  966. space.
  967. @c *********************************************************************
  968. @node Utilities
  969. @chapter Utilities
  970. This section describes tools primarily targeted at developers and users
  971. who write new package definitions. They complement the Scheme
  972. programming interface of Guix in a convenient way.
  973. @menu
  974. * Invoking guix build:: Building packages from the command line.
  975. * Invoking guix download:: Downloading a file and printing its hash.
  976. * Invoking guix hash:: Computing the cryptographic hash of a file.
  977. * Invoking guix refresh:: Updating package definitions.
  978. @end menu
  979. @node Invoking guix build
  980. @section Invoking @command{guix build}
  981. The @command{guix build} command builds packages or derivations and
  982. their dependencies, and prints the resulting store paths. Note that it
  983. does not modify the user's profile---this is the job of the
  984. @command{guix package} command (@pxref{Invoking guix package}). Thus,
  985. it is mainly useful for distribution developers.
  986. The general syntax is:
  987. @example
  988. guix build @var{options} @var{package-or-derivation}@dots{}
  989. @end example
  990. @var{package-or-derivation} may be either the name of a package found in
  991. the software distribution such as @code{coreutils} or
  992. @code{coreutils-8.20}, or a derivation such as
  993. @file{/nix/store/@dots{}-coreutils-8.19.drv}. Alternatively, the
  994. @code{--expression} option may be used to specify a Scheme expression
  995. that evaluates to a package; this is useful when disambiguation among
  996. several same-named packages or package variants is needed.
  997. The @var{options} may be zero or more of the following:
  998. @table @code
  999. @item --expression=@var{expr}
  1000. @itemx -e @var{expr}
  1001. Build the package @var{expr} evaluates to.
  1002. For example, @var{expr} may be @code{(@@ (gnu packages guile)
  1003. guile-1.8)}, which unambiguously designates this specific variant of
  1004. version 1.8 of Guile.
  1005. @item --source
  1006. @itemx -S
  1007. Build the packages' source derivations, rather than the packages
  1008. themselves.
  1009. For instance, @code{guix build -S gcc} returns something like
  1010. @file{/nix/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
  1011. @item --system=@var{system}
  1012. @itemx -s @var{system}
  1013. Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
  1014. the host's system type.
  1015. An example use of this is on Linux-based systems, which can emulate
  1016. different personalities. For instance, passing
  1017. @code{--system=i686-linux} on an @code{x86_64-linux} system allows users
  1018. to build packages in a complete 32-bit environment.
  1019. @item --target=@var{triplet}
  1020. @cindex cross-compilation
  1021. Cross-build for @var{triplet}, which must be a valid GNU triplet, such
  1022. as @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU
  1023. configuration triplets,, configure, GNU Configure and Build System}).
  1024. @item --derivations
  1025. @itemx -d
  1026. Return the derivation paths, not the output paths, of the given
  1027. packages.
  1028. @item --keep-failed
  1029. @itemx -K
  1030. Keep the build tree of failed builds. Thus, if a build fail, its build
  1031. tree is kept under @file{/tmp}, in a directory whose name is shown at
  1032. the end of the build log. This is useful when debugging build issues.
  1033. @item --dry-run
  1034. @itemx -n
  1035. Do not build the derivations.
  1036. @item --fallback
  1037. When substituting a pre-built binary fails, fall back to building
  1038. packages locally.
  1039. @item --no-substitutes
  1040. Build instead of resorting to pre-built substitutes.
  1041. @item --max-silent-time=@var{seconds}
  1042. When the build or substitution process remains silent for more than
  1043. @var{seconds}, terminate it and report a build failure.
  1044. @item --cores=@var{n}
  1045. @itemx -c @var{n}
  1046. Allow the use of up to @var{n} CPU cores for the build. The special
  1047. value @code{0} means to use as many CPU cores as available.
  1048. @item --root=@var{file}
  1049. @itemx -r @var{file}
  1050. Make @var{file} a symlink to the result, and register it as a garbage
  1051. collector root.
  1052. @item --verbosity=@var{level}
  1053. Use the given verbosity level. @var{level} must be an integer between 0
  1054. and 5; higher means more verbose output. Setting a level of 4 or more
  1055. may be helpful when debugging setup issues with the build daemon.
  1056. @end table
  1057. Behind the scenes, @command{guix build} is essentially an interface to
  1058. the @code{package-derivation} procedure of the @code{(guix packages)}
  1059. module, and to the @code{build-derivations} procedure of the @code{(guix
  1060. store)} module.
  1061. @node Invoking guix download
  1062. @section Invoking @command{guix download}
  1063. When writing a package definition, developers typically need to download
  1064. the package's source tarball, compute its SHA256 hash, and write that
  1065. hash in the package definition (@pxref{Defining Packages}). The
  1066. @command{guix download} tool helps with this task: it downloads a file
  1067. from the given URI, adds it to the store, and prints both its file name
  1068. in the store and its SHA256 hash.
  1069. The fact that the downloaded file is added to the store saves bandwidth:
  1070. when the developer eventually tries to build the newly defined package
  1071. with @command{guix build}, the source tarball will not have to be
  1072. downloaded again because it is already in the store. It is also a
  1073. convenient way to temporarily stash files, which may be deleted
  1074. eventually (@pxref{Invoking guix gc}).
  1075. The @command{guix download} command supports the same URIs as used in
  1076. package definitions. In particular, it supports @code{mirror://} URIs.
  1077. @code{https} URIs (HTTP over TLS) are supported @emph{provided} the
  1078. Guile bindings for GnuTLS are available in the user's environment; when
  1079. they are not available, an error is raised.
  1080. The following option is available:
  1081. @table @code
  1082. @item --format=@var{fmt}
  1083. @itemx -f @var{fmt}
  1084. Write the hash in the format specified by @var{fmt}. For more
  1085. information on the valid values for @var{fmt}, @ref{Invoking guix hash}.
  1086. @end table
  1087. @node Invoking guix hash
  1088. @section Invoking @command{guix hash}
  1089. The @command{guix hash} command computes the SHA256 hash of a file.
  1090. It is primarily a convenience tool for anyone contributing to the
  1091. distribution: it computes the cryptographic hash of a file, which can be
  1092. used in the definition of a package (@pxref{Defining Packages}).
  1093. The general syntax is:
  1094. @example
  1095. guix hash @var{option} @var{file}
  1096. @end example
  1097. @command{guix hash} has the following option:
  1098. @table @code
  1099. @item --format=@var{fmt}
  1100. @itemx -f @var{fmt}
  1101. Write the hash in the format specified by @var{fmt}.
  1102. Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
  1103. (@code{hex} and @code{hexadecimal} can be used as well).
  1104. If the @option{--format} option is not specified, @command{guix hash}
  1105. will output the hash in @code{nix-base32}. This representation is used
  1106. in the definitions of packages.
  1107. @end table
  1108. @node Invoking guix refresh
  1109. @section Invoking @command{guix refresh}
  1110. The primary audience of the @command{guix refresh} command is developers
  1111. of the GNU software distribution. By default, it reports any packages
  1112. provided by the distribution that are outdated compared to the latest
  1113. upstream version, like this:
  1114. @example
  1115. $ guix refresh
  1116. gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
  1117. gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
  1118. @end example
  1119. It does so by browsing each package's FTP directory and determining the
  1120. highest version number of the source tarballs
  1121. therein@footnote{Currently, this only works for GNU packages.}.
  1122. When passed @code{--update}, it modifies distribution source files to
  1123. update the version numbers and source tarball hashes of those packages'
  1124. recipes (@pxref{Defining Packages}). This is achieved by downloading
  1125. each package's latest source tarball and its associated OpenPGP
  1126. signature, authenticating the downloaded tarball against its signature
  1127. using @command{gpg}, and finally computing its hash. When the public
  1128. key used to sign the tarball is missing from the user's keyring, an
  1129. attempt is made to automatically retrieve it from a public key server;
  1130. when it's successful, the key is added to the user's keyring; otherwise,
  1131. @command{guix refresh} reports an error.
  1132. The following options are supported:
  1133. @table @code
  1134. @item --update
  1135. @itemx -u
  1136. Update distribution source files (package recipes) in place.
  1137. @ref{Defining Packages}, for more information on package definitions.
  1138. @item --select=[@var{subset}]
  1139. @itemx -s @var{subset}
  1140. Select all the packages in @var{subset}, one of @code{core} or
  1141. @code{non-core}.
  1142. The @code{core} subset refers to all the packages at the core of the
  1143. distribution---i.e., packages that are used to build ``everything
  1144. else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
  1145. changing one of these packages in the distribution entails a rebuild of
  1146. all the others. Thus, such updates are an inconvenience to users in
  1147. terms of build time or bandwidth used to achieve the upgrade.
  1148. The @code{non-core} subset refers to the remaining packages. It is
  1149. typically useful in cases where an update of the core packages would be
  1150. inconvenient.
  1151. @end table
  1152. In addition, @command{guix refresh} can be passed one or more package
  1153. names, as in this example:
  1154. @example
  1155. guix refresh -u emacs idutils
  1156. @end example
  1157. @noindent
  1158. The command above specifically updates the @code{emacs} and
  1159. @code{idutils} packages. The @code{--select} option would have no
  1160. effect in this case.
  1161. The following options can be used to customize GnuPG operation:
  1162. @table @code
  1163. @item --key-server=@var{host}
  1164. Use @var{host} as the OpenPGP key server when importing a public key.
  1165. @item --gpg=@var{command}
  1166. Use @var{command} as the GnuPG 2.x command. @var{command} is searched
  1167. for in @code{$PATH}.
  1168. @end table
  1169. @c *********************************************************************
  1170. @node GNU Distribution
  1171. @chapter GNU Distribution
  1172. Guix comes with a distribution of free software@footnote{The term
  1173. ``free'' here refers to the
  1174. @url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
  1175. users of that software}.} that form the basis of the GNU system. This
  1176. includes core GNU packages such as GNU libc, GCC, and Binutils, as well
  1177. as many GNU and non-GNU applications. The complete list of available
  1178. packages can be seen by running @command{guix package} (@pxref{Invoking
  1179. guix package}):
  1180. @example
  1181. guix package --list-available
  1182. @end example
  1183. Our goal is to build a practical 100% free software distribution of
  1184. Linux-based and other variants of GNU, with a focus on the promotion and
  1185. tight integration of GNU components, and an emphasis on programs and
  1186. tools that help users exert that freedom.
  1187. @menu
  1188. * Installing Debugging Files:: Feeding the debugger.
  1189. * Package Modules:: Packages from the programmer's viewpoint.
  1190. * Packaging Guidelines:: Growing the distribution.
  1191. * Bootstrapping:: GNU/Linux built from scratch.
  1192. * Porting:: Targeting another platform or kernel.
  1193. @end menu
  1194. Building this distribution is a cooperative effort, and you are invited
  1195. to join! @ref{Contributing}, for information about how you can help.
  1196. @node Installing Debugging Files
  1197. @section Installing Debugging Files
  1198. Program binaries, as produced by the GCC compilers for instance, are
  1199. typically written in the ELF format, with a section containing
  1200. @dfn{debugging information}. Debugging information is what allows the
  1201. debugger, GDB, to map binary code to source code; it is required to
  1202. debug a compiled program in good conditions.
  1203. The problem with debugging information is that is takes up a fair amount
  1204. of disk space. For example, debugging information for the GNU C Library
  1205. weighs in at more than 60 MiB. Thus, as a user, keeping all the
  1206. debugging info of all the installed programs is usually not an option.
  1207. Yet, space savings should not come at the cost of an impediment to
  1208. debugging---especially in the GNU system, which should make it easier
  1209. for users to exert their computing freedom (@pxref{GNU Distribution}).
  1210. Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
  1211. mechanism that allows users to get the best of both worlds: debugging
  1212. information can be stripped from the binaries and stored in separate
  1213. files. GDB is then able to load debugging information from those files,
  1214. when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
  1215. with GDB}).
  1216. The GNU distribution takes advantage of this by storing debugging
  1217. information in the @code{lib/debug} sub-directory of a separate package
  1218. output unimaginatively called @code{debug} (@pxref{Packages with
  1219. Multiple Outputs}). Users can choose to install the @code{debug} output
  1220. of a package when they need it. For instance, the following command
  1221. installs the debugging information for the GNU C Library and for GNU
  1222. Guile:
  1223. @example
  1224. guix package -i glibc:debug -i guile:debug
  1225. @end example
  1226. GDB must then be told to look for debug files in the user's profile, by
  1227. setting the @code{debug-file-directory} variable (consider setting it
  1228. from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
  1229. GDB}):
  1230. @example
  1231. (gdb) set debug-file-directory ~/.guix-profile/lib/debug
  1232. @end example
  1233. From there on, GDB will pick up debugging information from the
  1234. @code{.debug} files under @file{~/.guix-profile/lib/debug}.
  1235. @c XXX: keep me up-to-date
  1236. The @code{debug} output mechanism in Guix is implemented by the
  1237. @code{gnu-build-system} (@pxref{Defining Packages}). Currently, it is
  1238. opt-in---debugging information is available only for those packages
  1239. whose definition explicitly declares a @code{debug} output. This may be
  1240. changed to opt-out in the future, if our build farm servers can handle
  1241. the load. To check whether a package has a @code{debug} output, use
  1242. @command{guix package --list-available} (@pxref{Invoking guix package}).
  1243. @node Package Modules
  1244. @section Package Modules
  1245. From a programming viewpoint, the package definitions of the
  1246. distribution are provided by Guile modules in the @code{(gnu packages
  1247. ...)} name space (@pxref{Modules, Guile modules,, guile, GNU Guile
  1248. Reference Manual}). For instance, the @code{(gnu packages emacs)}
  1249. module exports a variable named @code{emacs}, which is bound to a
  1250. @code{<package>} object (@pxref{Defining Packages}). The @code{(gnu
  1251. packages)} module provides facilities for searching for packages.
  1252. The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
  1253. each package is built based solely on other packages in the
  1254. distribution. The root of this dependency graph is a small set of
  1255. @dfn{bootstrap binaries}, provided by the @code{(gnu packages
  1256. bootstrap)} module. For more information on bootstrapping,
  1257. @ref{Bootstrapping}.
  1258. @node Packaging Guidelines
  1259. @section Packaging Guidelines
  1260. The GNU distribution is nascent and may well lack some of your favorite
  1261. packages. This section describes how you can help make the distribution
  1262. grow. @ref{Contributing}, for additional information on how you can
  1263. help.
  1264. Free software packages are usually distributed in the form of
  1265. @dfn{source code tarballs}---typically @file{tar.gz} files that contain
  1266. all the source files. Adding a package to the distribution means
  1267. essentially two things: adding a @dfn{recipe} that describes how to
  1268. build the package, including a list of other packages required to build
  1269. it, and adding @dfn{package meta-data} along with that recipe, such as a
  1270. description and licensing information.
  1271. In Guix all this information is embodied in @dfn{package definitions}.
  1272. Package definitions provide a high-level view of the package. They are
  1273. written using the syntax of the Scheme programming language; in fact,
  1274. for each package we define a variable bound to the package definition,
  1275. and export that variable from a module (@pxref{Package Modules}).
  1276. However, in-depth Scheme knowledge is @emph{not} a prerequisite for
  1277. creating packages. For more information on package definitions,
  1278. @ref{Defining Packages}.
  1279. Once a package definition is in place, stored in a file in the Guix
  1280. source tree, it can be tested using the @command{guix build} command
  1281. (@pxref{Invoking guix build}). For example, assuming the new package is
  1282. called @code{gnew}, you may run this command from the Guix build tree:
  1283. @example
  1284. ./pre-inst-env guix build gnew --keep-failed
  1285. @end example
  1286. Using @code{--keep-failed} makes it easier to debug build failures since
  1287. it provides access to the failed build tree.
  1288. Once your package builds correctly, please send us a patch
  1289. (@pxref{Contributing}). Well, if you need help, we will be happy to
  1290. help you too. Once the patch is committed in the Guix repository, the
  1291. new package automatically gets built on the supported platforms by
  1292. @url{http://hydra.gnu.org/gnu/master, our continuous integration
  1293. system}.
  1294. @cindex substituter
  1295. Users can obtain the new package definition simply by running
  1296. @command{guix pull} (@pxref{Invoking guix pull}). When
  1297. @code{hydra.gnu.org} is done building the package, installing the
  1298. package automatically downloads binaries from there (except when using
  1299. @code{--no-substitutes}). The only place where human intervention is
  1300. needed is to review and apply the patch.
  1301. @menu
  1302. * Software Freedom:: What may go into the distribution.
  1303. * Package Naming:: What's in a name?
  1304. * Version Numbers:: When the name is not enough.
  1305. * Python Modules:: Taming the snake.
  1306. @end menu
  1307. @node Software Freedom
  1308. @subsection Software Freedom
  1309. @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
  1310. The GNU operating system has been developed so that users can have
  1311. freedom in their computing. GNU is @dfn{free software}, meaning that
  1312. users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
  1313. essential freedoms}: to run the program, to study and change the program
  1314. in source code form, to redistribute exact copies, and to distribute
  1315. modified versions. Packages found in the GNU distribution provide only
  1316. software that conveys these four freedoms.
  1317. In addition, the GNU distribution follow the
  1318. @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
  1319. software distribution guidelines}. Among other things, these guidelines
  1320. reject non-free firmware, recommendations of non-free software, and
  1321. discuss ways to deal with trademarks and patents.
  1322. @node Package Naming
  1323. @subsection Package Naming
  1324. A package has actually two names associated to it:
  1325. First, there is the name of the @emph{Scheme variable}, the one following
  1326. @code{define-public}. By this name, the package can be made known in the
  1327. Scheme code, for instance as input to another package.
  1328. Second, there is the string in the @code{name} field of a package definition.
  1329. This name is used by the package manager.
  1330. Both are usually the same and correspond to the lowercase conversion of the
  1331. project name chosen by upstream. For instance, the GNUnet project is packaged
  1332. as @code{gnunet}. We do not add @code{lib} prefixes for library packages,
  1333. unless these are already part of the official project name.
  1334. But see @ref{Python Modules} for special rules concerning modules for
  1335. the Python language.
  1336. @node Version Numbers
  1337. @subsection Version Numbers
  1338. We usually package only the latest version of a given free software
  1339. project. But sometimes, for instance for incompatible library versions,
  1340. two (or more) versions of the same package are needed. These require different
  1341. Scheme variable names. We use the name as defined in @ref {Package Naming}
  1342. for the most recent version; previous versions use the same name, suffixed
  1343. by @code{-} and the smallest prefix of the version number that may
  1344. distinguish the two versions.
  1345. The name inside the package definition is the same for all versions of a
  1346. package and does not contain any version number.
  1347. For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
  1348. @example
  1349. (define-public gtk+
  1350. (package
  1351. (name "gtk+")
  1352. (version "3.9.12")
  1353. ...))
  1354. (define-public gtk+-2
  1355. (package
  1356. (name "gtk+")
  1357. (version "2.24.20")
  1358. ...))
  1359. @end example
  1360. If we also wanted GTK+ 3.8.2, this would be packaged as
  1361. @example
  1362. (define-public gtk+-3.8
  1363. (package
  1364. (name "gtk+")
  1365. (version "3.8.2")
  1366. ...))
  1367. @end example
  1368. @node Python Modules
  1369. @subsection Python Modules
  1370. We currently package Python 2 and Python 3, under the Scheme variable names
  1371. @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
  1372. To avoid confusion and naming clashes with other programming languages, it
  1373. seems desirable that the name of a package for a Python module contains
  1374. the word @code{python}.
  1375. Some modules are compatible with only one version of Python, others with both.
  1376. If the package Foo compiles only with Python 3, we name it
  1377. @code{python-foo}; if it compiles only with Python 2, we name it
  1378. @code{python2-foo}. If it is compatible with both versions, we create two
  1379. packages with the corresponding names.
  1380. If a project already contains the word @code{python}, we drop this;
  1381. for instance, the module python-dateutil is packaged under the names
  1382. @code{python-dateutil} and @code{python2-dateutil}.
  1383. @node Bootstrapping
  1384. @section Bootstrapping
  1385. @c Adapted from the ELS 2013 paper.
  1386. @cindex bootstrapping
  1387. Bootstrapping in our context refers to how the distribution gets built
  1388. ``from nothing''. Remember that the build environment of a derivation
  1389. contains nothing but its declared inputs (@pxref{Introduction}). So
  1390. there's an obvious chicken-and-egg problem: how does the first package
  1391. get built? How does the first compiler get compiled? Note that this is
  1392. a question of interest only to the curious hacker, not to the regular
  1393. user, so you can shamelessly skip this section if you consider yourself
  1394. a ``regular user''.
  1395. @cindex bootstrap binaries
  1396. The GNU system is primarily made of C code, with libc at its core. The
  1397. GNU build system itself assumes the availability of a Bourne shell and
  1398. command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
  1399. `grep'. Furthermore, build programs---programs that run
  1400. @code{./configure}, @code{make}, etc.---are written in Guile Scheme
  1401. (@pxref{Derivations}). Consequently, to be able to build anything at
  1402. all, from scratch, Guix relies on pre-built binaries of Guile, GCC,
  1403. Binutils, libc, and the other packages mentioned above---the
  1404. @dfn{bootstrap binaries}.
  1405. These bootstrap binaries are ``taken for granted'', though we can also
  1406. re-create them if needed (more on that later.)
  1407. @unnumberedsubsec Preparing to Use the Bootstrap Binaries
  1408. @c As of Emacs 24.3, Info-mode displays the image, but since it's a
  1409. @c large image, it's hard to scroll. Oh well.
  1410. @image{images/bootstrap-graph,,,Dependency graph of the early bootstrap derivations}
  1411. The figure above shows the very beginning of the dependency graph of the
  1412. distribution, corresponding to the package definitions of the @code{(gnu
  1413. packages bootstrap)} module. At this level of detail, things are
  1414. slightly complex. First, Guile itself consists of an ELF executable,
  1415. along with many source and compiled Scheme files that are dynamically
  1416. loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz}
  1417. tarball shown in this graph. This tarball is part of Guix's ``source''
  1418. distribution, and gets inserted into the store with @code{add-to-store}
  1419. (@pxref{The Store}).
  1420. But how do we write a derivation that unpacks this tarball and adds it
  1421. to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv}
  1422. derivation---the first one that gets built---uses @code{bash} as its
  1423. builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls
  1424. @code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar},
  1425. @file{xz}, and @file{mkdir} are statically-linked binaries, also part of
  1426. the Guix source distribution, whose sole purpose is to allow the Guile
  1427. tarball to be unpacked.
  1428. Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
  1429. Guile that can be used to run subsequent build programs. Its first task
  1430. is to download tarballs containing the other pre-built binaries---this
  1431. is what the @code{.tar.xz.drv} derivations do. Guix modules such as
  1432. @code{ftp-client.scm} are used for this purpose. The
  1433. @code{module-import.drv} derivations import those modules in a directory
  1434. in the store, using the original layout. The
  1435. @code{module-import-compiled.drv} derivations compile those modules, and
  1436. write them in an output directory with the right layout. This
  1437. corresponds to the @code{#:modules} argument of
  1438. @code{build-expression->derivation} (@pxref{Derivations}).
  1439. Finally, the various tarballs are unpacked by the
  1440. derivations @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv},
  1441. etc., at which point we have a working C tool chain.
  1442. @unnumberedsubsec Building the Build Tools
  1443. @c TODO: Add a package-level dependency graph generated from (gnu
  1444. @c packages base).
  1445. Bootstrapping is complete when we have a full tool chain that does not
  1446. depend on the pre-built bootstrap tools discussed above. This
  1447. no-dependency requirement is verified by checking whether the files of
  1448. the final tool chain contain references to the @file{/nix/store}
  1449. directories of the bootstrap inputs. The process that leads to this
  1450. ``final'' tool chain is described by the package definitions found in
  1451. the @code{(gnu packages base)} module.
  1452. @c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
  1453. The first tool that gets built with the bootstrap binaries is
  1454. GNU Make, which is a prerequisite for all the following packages.
  1455. From there Findutils and Diffutils get built.
  1456. Then come the first-stage Binutils and GCC, built as pseudo cross
  1457. tools---i.e., with @code{--target} equal to @code{--host}. They are
  1458. used to build libc. Thanks to this cross-build trick, this libc is
  1459. guaranteed not to hold any reference to the initial tool chain.
  1460. From there the final Binutils and GCC are built. GCC uses @code{ld}
  1461. from the final Binutils, and links programs against the just-built libc.
  1462. This tool chain is used to build the other packages used by Guix and by
  1463. the GNU Build System: Guile, Bash, Coreutils, etc.
  1464. And voilà! At this point we have the complete set of build tools that
  1465. the GNU Build System expects. These are in the @code{%final-inputs}
  1466. variables of the @code{(gnu packages base)} module, and are implicitly
  1467. used by any package that uses @code{gnu-build-system} (@pxref{Defining
  1468. Packages}).
  1469. @unnumberedsubsec Building the Bootstrap Binaries
  1470. Because the final tool chain does not depend on the bootstrap binaries,
  1471. those rarely need to be updated. Nevertheless, it is useful to have an
  1472. automated way to produce them, should an update occur, and this is what
  1473. the @code{(gnu packages make-bootstrap)} module provides.
  1474. The following command builds the tarballs containing the bootstrap
  1475. binaries (Guile, Binutils, GCC, libc, and a tarball containing a mixture
  1476. of Coreutils and other basic command-line tools):
  1477. @example
  1478. guix build bootstrap-tarballs
  1479. @end example
  1480. The generated tarballs are those that should be referred to in the
  1481. @code{(gnu packages bootstrap)} module mentioned at the beginning of
  1482. this section.
  1483. Still here? Then perhaps by now you've started to wonder: when do we
  1484. reach a fixed point? That is an interesting question! The answer is
  1485. unknown, but if you would like to investigate further (and have
  1486. significant computational and storage resources to do so), then let us
  1487. know.
  1488. @node Porting
  1489. @section Porting to a New Platform
  1490. As discussed above, the GNU distribution is self-contained, and
  1491. self-containment is achieved by relying on pre-built ``bootstrap
  1492. binaries'' (@pxref{Bootstrapping}). These binaries are specific to an
  1493. operating system kernel, CPU architecture, and application binary
  1494. interface (ABI). Thus, to port the distribution to a platform that is
  1495. not yet supported, one must build those bootstrap binaries, and update
  1496. the @code{(gnu packages bootstrap)} module to use them on that platform.
  1497. Fortunately, Guix can @emph{cross compile} those bootstrap binaries.
  1498. When everything goes well, and assuming the GNU tool chain supports the
  1499. target platform, this can be as simple as running a command like this
  1500. one:
  1501. @example
  1502. guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
  1503. @end example
  1504. In practice, there may be some complications. First, it may be that the
  1505. extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
  1506. above) is not recognized by all the GNU tools. Typically, glibc
  1507. recognizes some of these, whereas GCC uses an extra @code{--with-abi}
  1508. configure flag (see @code{gcc.scm} for examples of how to handle this.)
  1509. Second, some of the required packages could fail to build for that
  1510. platform. Lastly, the generated binaries could be broken for some
  1511. reason.
  1512. @c *********************************************************************
  1513. @node Contributing
  1514. @chapter Contributing
  1515. This project is a cooperative effort, and we need your help to make it
  1516. grow! Please get in touch with us on @email{guix-devel@@gnu.org}. We
  1517. welcome ideas, bug reports, patches, and anything that may be helpful to
  1518. the project. We particularly welcome help on packaging
  1519. (@pxref{Packaging Guidelines}).
  1520. Please see the
  1521. @url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING,
  1522. @file{HACKING} file} that comes with the Guix source code for practical
  1523. details about contributions.
  1524. @c *********************************************************************
  1525. @node Acknowledgments
  1526. @chapter Acknowledgments
  1527. Guix is based on the Nix package manager, which was designed and
  1528. implemented by Eelco Dolstra. Nix pioneered functional package
  1529. management, and promoted unprecedented features, such as transactional
  1530. package upgrades and rollbacks, per-user profiles, and referentially
  1531. transparent build processes. Without this work, Guix would not exist.
  1532. The Nix-based software distributions, Nixpkgs and NixOS, have also been
  1533. an inspiration for Guix.
  1534. @c *********************************************************************
  1535. @node GNU Free Documentation License
  1536. @appendix GNU Free Documentation License
  1537. @include fdl-1.3.texi
  1538. @c *********************************************************************
  1539. @node Concept Index
  1540. @unnumbered Concept Index
  1541. @printindex cp
  1542. @node Function Index
  1543. @unnumbered Function Index
  1544. @printindex fn
  1545. @bye
  1546. @c Local Variables:
  1547. @c ispell-local-dictionary: "american";
  1548. @c End: