records: Add `recutils->alist' for public consumption.
[guix:guix.git] / 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
7   Copying and distribution of this file, with or without modification,
8   are permitted in any medium without royalty provided the copyright
9   notice and this notice are preserved.
10
11
12 * Running Guix before it is installed
13
14 Command-line tools can be used even if you have not run "make install".
15 To do that, prefix each command with ‘./pre-inst-env’, as in:
16
17   ./pre-inst-env guix build --help
18
19 Similarly, for a Guile session using the Guix modules:
20
21   ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
22
23 The ‘pre-inst-env’ script sets up all the environment variables
24 necessary to support this.
25
26 * The Perfect Setup
27
28 The Perfect Setup to hack on Guix is basically the perfect setup used
29 for Guile hacking (info "(guile) Using Guile in Emacs").  First, you
30 need more than an editor, you need [[http://www.gnu.org/software/emacs][Emacs]], empowered by the wonderful
31 [[http://nongnu.org/geiser/][Geiser]].
32
33 Geiser allows for interactive and incremental development from within
34 Emacs: code compilation and evaluation from within buffers, access to
35 on-line documentation (docstrings), context-sensitive completion, M-. to
36 jump to an object definition, a REPL to try out your code, and more.
37
38 To actually edit the code, Emacs already has a neat Scheme mode.  But in
39 addition to that, you must not miss [[http://www.emacswiki.org/emacs/ParEdit][Paredit]].  It provides facilities to
40 directly operate on the syntax tree, such as raising an s-expression or
41 wrapping it, swallowing or rejecting the following s-expression, etc.
42
43 * Adding new packages
44
45 Package recipes in Guix look like this:
46
47 #+BEGIN_SRC scheme
48   (package
49     (name "nettle")
50     (version "2.5")
51     (source
52       (origin
53         (method url-fetch)
54         (uri (string-append "mirror://gnu/nettle/nettle-"
55                             version ".tar.gz"))
56         (sha256
57           (base32
58             "0wicr7amx01l03rm0pzgr1qvw3f9blaw17vjsy1301dh13ll58aa"))))
59     (build-system gnu-build-system)
60     (inputs `(("m4" ,m4)))
61     (propagated-inputs `(("gmp" ,gmp)))
62     (home-page
63       "http://www.lysator.liu.se/~nisse/nettle/")
64     (synopsis "GNU Nettle, a cryptographic library")
65     (description
66       "Nettle is a cryptographic library...")
67     (license gpl2+))
68 #+END_SRC
69
70 Such a recipe can be written by hand, and then tested by running
71 ‘./pre-inst-env guix build nettle’.
72
73 When writing the recipe, the base32-encoded SHA256 hash of the source
74 code tarball, which can be seen in the example above, can be obtained by
75 running:
76
77   guix download http://ftp.gnu.org/gnu/nettle/nettle-2.5.tar.gz
78
79 Alternatively, it is possible to semi-automatically import recipes from
80 the [[http://nixos.org/nixpkgs/][Nixpkgs]] software distribution using this command:
81
82   guix import /path/to/nixpkgs/checkout nettle
83
84 The command automatically fetches and converts to Guix the “Nix
85 expression” of Nettle.
86
87 * Submitting Patches
88
89 Development is done using the Git distributed version control system.  Thus,
90 access to the repository is not strictly necessary.  We welcome contributions
91 in the form of patches as produced by ‘git format-patch’ sent to
92 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]].
93
94 As you become a regular contributor, you may find it convenient to have write
95 access to the repository (see below.)
96
97 * Commit Access
98
99 For frequent contributors, having write access to the repository is
100 convenient.  When you deem it necessary, feel free to ask for it on the
101 mailing list.  When you get commit access, please make sure to follow the
102 policy below (discussions of the policy can take place on bug-guix@gnu.org.)
103
104 Non-trivial patches should always be posted to bug-guix@gnu.org (trivial
105 patches include fixing typos, etc.)
106
107 For patches that just add a new package, and a simple one, it’s OK to commit,
108 if you’re confident (which means you successfully built it in a chroot setup,
109 and have done a reasonable copyright and license auditing.)  Likewise for
110 package upgrades.  We have a mailing list for commit notifications
111 (guix-commits@gnu.org), so people can notice.  Before pushing your changes,
112 make sure to run ‘git pull --rebase’.
113
114 For anything else, please post to bug-guix@gnu.org and leave time for a
115 review, without committing anything.  If you didn’t receive any reply
116 after two weeks, and if you’re confident, it’s OK to commit.
117
118 That last part is subject to being adjusted, allowing individuals to commit
119 directly on non-controversial changes on parts they’re familiar with.