HACKING

   1 -*- mode: org; coding: utf-8; -*-
   2
   3 #+TITLE: Hacking GNU Guix and Its Incredible Distro
   4
   5 Copyright © 2012, 2013 Ludovic Courtès <ludo@gnu.org>
   6 Copyright © 2013 Nikita Karetnikov <nikita@karetnikov.org>
   7
   8   Copying and distribution of this file, with or without modification,
   9   are permitted in any medium without royalty provided the copyright
  10   notice and this notice are preserved.
  11
  12
  13 * Building from Git
  14
  15 When building Guix from a checkout, the following packages are required in
  16 addition to those mentioned in the installation instructions:
  17
  18   - [[http://www.gnu.org/software/autoconf/][GNU Autoconf]]
  19   - [[http://www.gnu.org/software/automake/][GNU Automake]]
  20   - [[http://www.gnu.org/software/gettext/][GNU Gettext]]
  21   - [[http://www.graphviz.org/][Graphviz]]
  22
  23 Run ‘./bootstrap’ to download the Nix daemon source code and to generate the
  24 build system infrastructure using autoconf.  It reports an error if an
  25 inappropriate version of the above packages is being used.
  26
  27 The ‘bootstrap’ script, among other things, invokes ‘git submodule update’; if
  28 you didn’t run it, you may get the following error:
  29
  30   make: *** No rule to make target `nix/libstore/schema.sql', needed by
  31   `nix/libstore/schema.sql.hh'
  32
  33 Then, as always, run ‘./configure’.  If you get an error like this one:
  34
  35   ./configure: line 6755: `PKG_CHECK_MODULES(GUILE, guile-2.0 >= 2.0.5)'
  36
  37 it probably means that Autoconf couldn’t find ‘pkg.m4’, which is provided by
  38 pkg-config.  Make sure that ‘pkg.m4’ is available.  For instance, if you
  39 installed Automake in ‘/usr/local’, it wouldn’t look for ‘.m4’ files in
  40 ‘/usr/share’.  So you have to invoke the following command in that case
  41
  42   $ export ACLOCAL_PATH=/usr/share/aclocal
  43
  44 See “info '(automake) Macro Search Path'” for more information.
  45
  46 Finally, you have to invoke ‘make check’ to run tests.  If anything fails,
  47 take a look at “info '(guix) Installation'” or send a message to
  48 <guix-devel@gnu.org>.
  49
  50 * Running Guix before it is installed
  51
  52 Command-line tools can be used even if you have not run "make install".
  53 To do that, prefix each command with ‘./pre-inst-env’, as in:
  54
  55   ./pre-inst-env guix build --help
  56
  57 Similarly, for a Guile session using the Guix modules:
  58
  59   ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
  60
  61 The ‘pre-inst-env’ script sets up all the environment variables
  62 necessary to support this.
  63
  64 * The Perfect Setup
  65
  66 The Perfect Setup to hack on Guix is basically the perfect setup used
  67 for Guile hacking (info "(guile) Using Guile in Emacs").  First, you
  68 need more than an editor, you need [[http://www.gnu.org/software/emacs][Emacs]], empowered by the wonderful
  69 [[http://nongnu.org/geiser/][Geiser]].
  70
  71 Geiser allows for interactive and incremental development from within
  72 Emacs: code compilation and evaluation from within buffers, access to
  73 on-line documentation (docstrings), context-sensitive completion, M-. to
  74 jump to an object definition, a REPL to try out your code, and more.
  75
  76 To actually edit the code, Emacs already has a neat Scheme mode.  But in
  77 addition to that, you must not miss [[http://www.emacswiki.org/emacs/ParEdit][Paredit]].  It provides facilities to
  78 directly operate on the syntax tree, such as raising an s-expression or
  79 wrapping it, swallowing or rejecting the following s-expression, etc.
  80
  81 * Adding new packages
  82
  83 Package recipes in Guix look like this:
  84
  85 #+BEGIN_SRC scheme
  86   (package
  87     (name "nettle")
  88     (version "2.5")
  89     (source
  90       (origin
  91         (method url-fetch)
  92         (uri (string-append "mirror://gnu/nettle/nettle-"
  93                             version ".tar.gz"))
  94         (sha256
  95           (base32
  96             "0wicr7amx01l03rm0pzgr1qvw3f9blaw17vjsy1301dh13ll58aa"))))
  97     (build-system gnu-build-system)
  98     (inputs `(("m4" ,m4)))
  99     (propagated-inputs `(("gmp" ,gmp)))
 100     (home-page
 101       "http://www.lysator.liu.se/~nisse/nettle/")
 102     (synopsis "GNU Nettle, a cryptographic library")
 103     (description
 104       "Nettle is a cryptographic library...")
 105     (license gpl2+))
 106 #+END_SRC
 107
 108 Such a recipe can be written by hand, and then tested by running
 109 ‘./pre-inst-env guix build nettle’.
 110
 111 When writing the recipe, the base32-encoded SHA256 hash of the source
 112 code tarball, which can be seen in the example above, can be obtained by
 113 running:
 114
 115   guix download http://ftp.gnu.org/gnu/nettle/nettle-2.5.tar.gz
 116
 117 Alternatively, it is possible to semi-automatically import recipes from
 118 the [[http://nixos.org/nixpkgs/][Nixpkgs]] software distribution using this command:
 119
 120   guix import /path/to/nixpkgs/checkout nettle
 121
 122 The command automatically fetches and converts to Guix the “Nix
 123 expression” of Nettle.
 124
 125 * Submitting Patches
 126
 127 Development is done using the Git distributed version control system.  Thus,
 128 access to the repository is not strictly necessary.  We welcome contributions
 129 in the form of patches as produced by ‘git format-patch’ sent to
 130 bug-guix@gnu.org.  Please write commit logs in the [[http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs][GNU ChangeLog format]].
 131
 132 As you become a regular contributor, you may find it convenient to have write
 133 access to the repository (see below.)
 134
 135 * Commit Access
 136
 137 For frequent contributors, having write access to the repository is
 138 convenient.  When you deem it necessary, feel free to ask for it on the
 139 mailing list.  When you get commit access, please make sure to follow the
 140 policy below (discussions of the policy can take place on bug-guix@gnu.org.)
 141
 142 Non-trivial patches should always be posted to bug-guix@gnu.org (trivial
 143 patches include fixing typos, etc.)
 144
 145 For patches that just add a new package, and a simple one, it’s OK to commit,
 146 if you’re confident (which means you successfully built it in a chroot setup,
 147 and have done a reasonable copyright and license auditing.)  Likewise for
 148 package upgrades.  We have a mailing list for commit notifications
 149 (guix-commits@gnu.org), so people can notice.  Before pushing your changes,
 150 make sure to run ‘git pull --rebase’.
 151
 152 For anything else, please post to bug-guix@gnu.org and leave time for a
 153 review, without committing anything.  If you didn’t receive any reply
 154 after two weeks, and if you’re confident, it’s OK to commit.
 155
 156 That last part is subject to being adjusted, allowing individuals to commit
 157 directly on non-controversial changes on parts they’re familiar with.