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 The "autoreconf -vi" command can be used to generate the build system
  51 infrastructure; it reports an error if an inappropriate version of the
  52 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) using Guix
  60   - re-run the configure script passing it the option
  61     `--with-libgcrypt-prefix=$HOME/.guix-profile/'
  62   - run "make" and "make install"
  63
  64 * How It Works
  65
  66 Guix does the high-level preparation of a /derivation/.  A derivation is
  67 the promise of a build; it is stored as a text file under
  68 =/nix/store/xxx.drv=.  The (guix derivations) module provides the
  69 `derivation' primitive, as well as higher-level wrappers such as
  70 `build-expression->derivation'.
  71
  72 Guix does remote procedure calls (RPCs) to the Guix or Nix daemon (the
  73 =guix-daemon= or =nix-daemon= command), which in turn performs builds
  74 and accesses to the Nix store on its behalf.  The RPCs are implemented
  75 in the (guix store) module.
  76
  77 * Installing Guix as non-root
  78
  79 The Guix daemon allows software builds to be performed under alternate
  80 user accounts, which are normally created specifically for this
  81 purpose.  For instance, you may have a pool of accounts in the
  82 =guixbuild= group, and then you can instruct =guix-daemon= to use them
  83 like this:
  84
  85   $ guix-daemon --build-users-group=guixbuild
  86
  87 However, unless it is run as root, =guix-daemon= cannot switch users.
  88 In that case, it falls back to using a setuid-root helper program call
  89 =nix-setuid-helper=.  That program is not setuid-root by default when
  90 you install it; instead you should run a command along these lines
  91 (assuming Guix is installed under /usr/local):
  92
  93   # chown root.root /usr/local/libexec/nix-setuid-helper
  94   # chmod 4755 /usr/local/libexec/nix-setuid-helper
  95
  96 * Contact
  97
  98 GNU Guix is hosted at https://savannah.gnu.org/projects/guix/.
  99
 100 Please email <bug-guix@gnu.org> for bug reports or questions regarding
 101 Guix and its distribution; email <gnu-system-discuss@gnu.org> for
 102 general issues regarding the GNU system.
 103
 104 Join #guix on irc.freenode.net.
 105
 106 * Guix & Nix
 107
 108 GNU Guix is based on [[http://nixos.org/nix/][the Nix package manager]].  It implements the same
 109 package deployment paradigm, and in fact it reuses some of its code.
 110 Yet, different engineering decisions were made for Guix, as described
 111 below.
 112
 113 Nix is really two things: a package build tool, implemented by a library
 114 and daemon, and a special-purpose programming language.  GNU Guix relies
 115 on the former, but uses Scheme as a replacement for the latter.
 116
 117 Using Scheme instead of a specific language allows us to get all the
 118 features and tooling that come with Guile (compiler, debugger, REPL,
 119 Unicode, libraries, etc.)  And it means that we have a general-purpose
 120 language, on top of which we can have embedded domain-specific languages
 121 (EDSLs), such as the one used to define packages.  This broadens what
 122 can be done in package recipes themselves, and what can be done around them.
 123
 124 Technically, Guix makes remote procedure calls to the ‘nix-worker’
 125 daemon to perform operations on the store.  At the lowest level, Nix
 126 “derivations” represent promises of a build, stored in ‘.drv’ files in
 127 the store.  Guix produces such derivations, which are then interpreted
 128 by the daemon to perform the build.  Thus, Guix derivations can use
 129 derivations produced by Nix (and vice versa).
 130
 131 With Nix and the [[http://nixos.org/nixpkgs][Nixpkgs]] distribution, package composition happens at
 132 the Nix language level, but builders are usually written in Bash.
 133 Conversely, Guix encourages the use of Scheme for both package
 134 composition and builders.  Likewise, the core functionality of Nix is
 135 written in C++ and Perl; Guix relies on some of the original C++ code,
 136 but exposes all the API as Scheme.
 137
 138 * Related software
 139
 140   - [[http://nixos.org][Nix, Nixpkgs, and NixOS]], functional package manager and associated
 141     software distribution, are the inspiration of Guix
 142   - [[http://www.gnu.org/software/stow/][GNU Stow]] builds around the idea of one directory per prefix, and a
 143     symlink tree to create user environments
 144   - [[http://www.pvv.ntnu.no/~arnej/store/storedoc_6.html][STORE]] shares the same idea
 145   - [[https://live.gnome.org/OSTree/][GNOME's OSTree]] allows bootable system images to be built from a
 146     specified set of packages
 147   - The [[http://www.gnu.org/s/gsrc/][GNU Source Release Collection]] (GSRC) is a user-land software
 148     distribution; unlike Guix, it relies on core tools available on the
 149     host system