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]], version 2.0.5 or later
  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