README

   1 -*- mode: org -*-
   2
   3 [[https://www.gnu.org/software/guix/][GNU Guix]] (IPA: /ɡiːks/) is a purely functional package manager, and
   4 associated free software distribution, for the [[https://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 [[https://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 [[https://nixos.org/nix/][Nix]] package manager.
  17
  18
  19 * Requirements
  20
  21 GNU Guix currently depends on the following packages:
  22
  23   - [[https://gnu.org/software/guile/][GNU Guile 2.2.x or 2.0.x]], version 2.0.9 or later
  24   - [[https://gnupg.org/][GNU libgcrypt]]
  25   - [[https://www.gnu.org/software/make/][GNU Make]]
  26   - optionally [[https://savannah.nongnu.org/projects/guile-json/][Guile-JSON]], for the 'guix import pypi' command
  27   - optionally [[https://www.gnutls.org][GnuTLS]] compiled with guile support enabled, for HTTPS support
  28     in the 'guix download' command.  Note that 'guix import pypi' requires
  29     this functionality.
  30
  31 Unless `--disable-daemon' was passed, the following packages are needed:
  32
  33   - [[https://sqlite.org/][SQLite 3]]
  34   - [[http://www.bzip.org][libbz2]]
  35   - [[https://gcc.gnu.org][GCC's g++]]
  36
  37 When `--disable-daemon' was passed, you instead need the following:
  38
  39   - [[https://nixos.org/nix/][Nix]]
  40
  41 * Installation
  42
  43 See the manual for the installation instructions, either by running
  44
  45   info -f doc/guix.info "Installation"
  46
  47 or by checking the [[https://www.gnu.org/software/guix/manual/guix.html#Installation][web copy of the manual]].
  48
  49 For information on installation from a Git checkout, please see the section
  50 "Building from Git" in the manual.
  51
  52 * Installing Guix from Guix
  53
  54 You can re-build and re-install Guix using a system that already runs Guix.
  55 To do so:
  56
  57   - Start a shell with the development environment for Guix:
  58
  59       guix environment guix
  60
  61   - Re-run the 'configure' script passing it the option
  62     '--localstatedir=/somewhere', where '/somewhere' is the 'localstatedir'
  63     value of the currently installed Guix (failing to do that would lead the
  64     new Guix to consider the store to be empty!).
  65
  66   - Run "make", "make check", and "make install".
  67
  68 * How It Works
  69
  70 Guix does the high-level preparation of a /derivation/.  A derivation is
  71 the promise of a build; it is stored as a text file under
  72 =/gnu/store/xxx.drv=.  The (guix derivations) module provides the
  73 `derivation' primitive, as well as higher-level wrappers such as
  74 `build-expression->derivation'.
  75
  76 Guix does remote procedure calls (RPCs) to the Guix or Nix daemon (the
  77 =guix-daemon= or =nix-daemon= command), which in turn performs builds
  78 and accesses to the Nix store on its behalf.  The RPCs are implemented
  79 in the (guix store) module.
  80
  81 * Installing Guix as non-root
  82
  83 The Guix daemon allows software builds to be performed under alternate
  84 user accounts, which are normally created specifically for this
  85 purpose.  For instance, you may have a pool of accounts in the
  86 =guixbuild= group, and then you can instruct =guix-daemon= to use them
  87 like this:
  88
  89   $ guix-daemon --build-users-group=guixbuild
  90
  91 However, unless it is run as root, =guix-daemon= cannot switch users.
  92 In that case, it falls back to using a setuid-root helper program call
  93 =nix-setuid-helper=.  That program is not setuid-root by default when
  94 you install it; instead you should run a command along these lines
  95 (assuming Guix is installed under /usr/local):
  96
  97   # chown root.root /usr/local/libexec/nix-setuid-helper
  98   # chmod 4755 /usr/local/libexec/nix-setuid-helper
  99
 100 * Contact
 101
 102 GNU Guix is hosted at https://savannah.gnu.org/projects/guix/.
 103
 104 Please email <bug-guix@gnu.org> for bug reports or questions regarding
 105 Guix and its distribution; email <gnu-system-discuss@gnu.org> for
 106 general issues regarding the GNU system.
 107
 108 Join #guix on irc.freenode.net.
 109
 110 * Guix & Nix
 111
 112 GNU Guix is based on [[https://nixos.org/nix/][the Nix package manager]].  It implements the same
 113 package deployment paradigm, and in fact it reuses some of its code.
 114 Yet, different engineering decisions were made for Guix, as described
 115 below.
 116
 117 Nix is really two things: a package build tool, implemented by a library
 118 and daemon, and a special-purpose programming language.  GNU Guix relies
 119 on the former, but uses Scheme as a replacement for the latter.
 120
 121 Using Scheme instead of a specific language allows us to get all the
 122 features and tooling that come with Guile (compiler, debugger, REPL,
 123 Unicode, libraries, etc.)  And it means that we have a general-purpose
 124 language, on top of which we can have embedded domain-specific languages
 125 (EDSLs), such as the one used to define packages.  This broadens what
 126 can be done in package recipes themselves, and what can be done around them.
 127
 128 Technically, Guix makes remote procedure calls to the ‘nix-worker’
 129 daemon to perform operations on the store.  At the lowest level, Nix
 130 “derivations” represent promises of a build, stored in ‘.drv’ files in
 131 the store.  Guix produces such derivations, which are then interpreted
 132 by the daemon to perform the build.  Thus, Guix derivations can use
 133 derivations produced by Nix (and vice versa).
 134
 135 With Nix and the [[https://nixos.org/nixpkgs][Nixpkgs]] distribution, package composition happens at
 136 the Nix language level, but builders are usually written in Bash.
 137 Conversely, Guix encourages the use of Scheme for both package
 138 composition and builders.  Likewise, the core functionality of Nix is
 139 written in C++ and Perl; Guix relies on some of the original C++ code,
 140 but exposes all the API as Scheme.
 141
 142 * Related software
 143
 144   - [[https://nixos.org][Nix, Nixpkgs, and NixOS]], functional package manager and associated
 145     software distribution, are the inspiration of Guix
 146   - [[https://www.gnu.org/software/stow/][GNU Stow]] builds around the idea of one directory per prefix, and a
 147     symlink tree to create user environments
 148   - [[https://www.pvv.ntnu.no/~arnej/store/storedoc_6.html][STORE]] shares the same idea
 149   - [[https://live.gnome.org/OSTree/][GNOME's OSTree]] allows bootable system images to be built from a
 150     specified set of packages
 151   - The [[https://www.gnu.org/s/gsrc/][GNU Source Release Collection]] (GSRC) is a user-land software
 152     distribution; unlike Guix, it relies on core tools available on the
 153     host system