records: Add `recutils->alist' for public consumption.
[guix:guix.git] / README
1 -*- mode: org -*-
2
3 [[http://www.gnu.org/software/guix/][GNU Guix]] (IPA: /ɡiːks/) is a purely functional package manager, and
4 associated free software distribution, for the [[http://www.gnu.org/gnu/gnu.html][GNU system]].  In addition
5 to standard package management features, Guix supports transactional
6 upgrades and roll-backs, unprivileged package management, per-user
7 profiles, and garbage collection.
8
9 It provides [[http://www.gnu.org/software/guile/][Guile]] Scheme APIs, including a high-level embedded
10 domain-specific languages (EDSLs) to describe how packages are to be
11 built and composed.
12
13 A user-land free software distribution for GNU/Linux comes as part of
14 Guix.
15
16 Guix is based on the [[http://nixos.org/nix/][Nix]] package manager.
17
18
19 * Requirements
20
21 GNU Guix currently depends on the following packages:
22
23   - [[http://gnu.org/software/guile/][GNU Guile 2.0.x]]
24   - [[http://gnupg.org/][GNU libgcrypt]]
25
26 Unless `--disable-daemon' was passed, the following packages are needed:
27
28   - [[http://sqlite.org/][SQLite 3]]
29   - [[http://www.bzip.org][libbz2]]
30   - [[http://gcc.gnu.org][GCC's g++]]
31
32 When `--disable-daemon' was passed, you instead need the following:
33
34   - [[http://nixos.org/nix/][Nix]]
35
36 Optionally, packages from Nixpkgs may be transparently reused from Guix.
37 For this to work, you need to have a checkout of the Nixpkgs repository;
38 the `--with-nixpkgs' option allows you to let `configure' know where the
39 Nixpkgs checkout is.
40
41   - [[http://nixos.org/nixpkgs/][Nixpkgs]]
42
43 When building Guix from a checkout, the following packages are also
44 required:
45
46   - [[http://www.gnu.org/software/autoconf/][GNU Autoconf]]
47   - [[http://www.gnu.org/software/automake/][GNU Automake]]
48   - [[http://www.gnu.org/software/gettext/][GNU Gettext]]
49
50 Run the "bootstrap" script to download the Nix daemon and to generate the
51 build system infrastructure using autoconf. It reports an error if an
52 inappropriate version of the above packages is being used.
53
54 * Installing Guix from Guix
55
56 You can re-build and re-install Guix using a system that already runs Guix.
57 To do so:
58
59   - Install the dependencies (see 'Requirements' above) and build tools using
60     Guix.  You should have the following packages installed in your user
61     profile:
62
63     - autoconf
64     - automake
65     - bzip2
66     - gcc
67     - gettext
68     - glibc
69     - guile
70     - ld-wrapper
71     - libgcrypt
72     - pkg-config
73     - sqlite
74
75   - set the environment variables that Guix recommends you to set during the
76     package installation process:
77       ACLOCAL, CPATH, LIBRARY_PATH, PATH, PKG_CONFIG_PATH
78     In addition, set 
79       GUIX_LD_WRAPPER_ALLOW_IMPURITIES=yes
80
81   - re-run the configure script passing it the option
82     `--with-libgcrypt-prefix=$HOME/.guix-profile/'
83
84   - run "make" and "make install"
85
86 * How It Works
87
88 Guix does the high-level preparation of a /derivation/.  A derivation is
89 the promise of a build; it is stored as a text file under
90 =/nix/store/xxx.drv=.  The (guix derivations) module provides the
91 `derivation' primitive, as well as higher-level wrappers such as
92 `build-expression->derivation'.
93
94 Guix does remote procedure calls (RPCs) to the Guix or Nix daemon (the
95 =guix-daemon= or =nix-daemon= command), which in turn performs builds
96 and accesses to the Nix store on its behalf.  The RPCs are implemented
97 in the (guix store) module.
98
99 * Installing Guix as non-root
100
101 The Guix daemon allows software builds to be performed under alternate
102 user accounts, which are normally created specifically for this
103 purpose.  For instance, you may have a pool of accounts in the
104 =guixbuild= group, and then you can instruct =guix-daemon= to use them
105 like this:
106
107   $ guix-daemon --build-users-group=guixbuild
108
109 However, unless it is run as root, =guix-daemon= cannot switch users.
110 In that case, it falls back to using a setuid-root helper program call
111 =nix-setuid-helper=.  That program is not setuid-root by default when
112 you install it; instead you should run a command along these lines
113 (assuming Guix is installed under /usr/local):
114
115   # chown root.root /usr/local/libexec/nix-setuid-helper
116   # chmod 4755 /usr/local/libexec/nix-setuid-helper
117
118 * Contact
119
120 GNU Guix is hosted at https://savannah.gnu.org/projects/guix/.
121
122 Please email <bug-guix@gnu.org> for bug reports or questions regarding
123 Guix and its distribution; email <gnu-system-discuss@gnu.org> for
124 general issues regarding the GNU system.
125
126 Join #guix on irc.freenode.net.
127
128 * Guix & Nix
129
130 GNU Guix is based on [[http://nixos.org/nix/][the Nix package manager]].  It implements the same
131 package deployment paradigm, and in fact it reuses some of its code.
132 Yet, different engineering decisions were made for Guix, as described
133 below.
134
135 Nix is really two things: a package build tool, implemented by a library
136 and daemon, and a special-purpose programming language.  GNU Guix relies
137 on the former, but uses Scheme as a replacement for the latter.
138
139 Using Scheme instead of a specific language allows us to get all the
140 features and tooling that come with Guile (compiler, debugger, REPL,
141 Unicode, libraries, etc.)  And it means that we have a general-purpose
142 language, on top of which we can have embedded domain-specific languages
143 (EDSLs), such as the one used to define packages.  This broadens what
144 can be done in package recipes themselves, and what can be done around them.
145
146 Technically, Guix makes remote procedure calls to the ‘nix-worker’
147 daemon to perform operations on the store.  At the lowest level, Nix
148 “derivations” represent promises of a build, stored in ‘.drv’ files in
149 the store.  Guix produces such derivations, which are then interpreted
150 by the daemon to perform the build.  Thus, Guix derivations can use
151 derivations produced by Nix (and vice versa).
152
153 With Nix and the [[http://nixos.org/nixpkgs][Nixpkgs]] distribution, package composition happens at
154 the Nix language level, but builders are usually written in Bash.
155 Conversely, Guix encourages the use of Scheme for both package
156 composition and builders.  Likewise, the core functionality of Nix is
157 written in C++ and Perl; Guix relies on some of the original C++ code,
158 but exposes all the API as Scheme.
159
160 * Related software
161
162   - [[http://nixos.org][Nix, Nixpkgs, and NixOS]], functional package manager and associated
163     software distribution, are the inspiration of Guix
164   - [[http://www.gnu.org/software/stow/][GNU Stow]] builds around the idea of one directory per prefix, and a
165     symlink tree to create user environments
166   - [[http://www.pvv.ntnu.no/~arnej/store/storedoc_6.html][STORE]] shares the same idea
167   - [[https://live.gnome.org/OSTree/][GNOME's OSTree]] allows bootable system images to be built from a
168     specified set of packages
169   - The [[http://www.gnu.org/s/gsrc/][GNU Source Release Collection]] (GSRC) is a user-land software
170     distribution; unlike Guix, it relies on core tools available on the
171     host system