guix - HACKING

164 lines · 7.2 KiB

1	-- mode: org; coding: utf-8; --
2
3	#+TITLE: Hacking GNU Guix and Its Incredible Distro
4
5	Copyright © 2012, 2013 Ludovic Courtès <[email protected]>
6	Copyright © 2013 Nikita Karetnikov <[email protected]>
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	<[email protected]>.
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	* Submitting Patches
82
83	Development is done using the Git distributed version control system. Thus,
84	access to the repository is not strictly necessary. We welcome contributions
85	in the form of patches as produced by ‘git format-patch’ sent to
86	[email protected]. Please write commit logs in the [[http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs][GNU ChangeLog format]].
87
88	As you become a regular contributor, you may find it convenient to have write
89	access to the repository (see below.)
90
91	* Coding Style
92
93	In general our code follows the [[info:standards][GNU Coding Standards]] (GCS). However, the GCS
94	do not say much about Scheme, so here are some additional rules.
95
96	** Programming Paradigm
97
98	Scheme code in Guix is written in a purely functional style. One exception is
99	code that involves input/output, and procedures that implement low-level
100	concepts, such as the ‘memoize’ procedure.
101
102	** Modules
103
104	Guile modules that are meant to be used on the builder side must live in the
105	(guix build …) name space. They must not refer to other Guix or GNU modules.
106	However, it is OK for a “host-side” module to use a build-side module.
107
108	Modules that deal with the broader GNU system should be in the (gnu …) name
109	space rather than (guix …).
110
111	** Data Types and Pattern Matching
112
113	The tendency in classical Lisp is to use lists to represent everything, and
114	then to browse them “by hand” using ‘car’, ‘cdr’, ‘cadr’, and co. There are
115	several problems with that style, notably the fact that it is hard to read,
116	error-prone, and a hindrance to proper type error reports.
117
118	Guix code should define appropriate data types (for instance, using
119	‘define-record-type*’) rather than abuse lists. In addition, it should use
120	pattern matching, via Guile’s (ice-9 match) module, especially when matching
121	lists.
122
123	** Formatting Code
124
125	When writing Scheme code, we follow common wisdom among Scheme programmers.
126	In general, we follow the [[http://mumble.net/~campbell/scheme/style.txt][Riastradh's Lisp Style Rules]]. This document happens
127	to describe the conventions mostly used in Guile’s code too. It is very
128	thoughtful and well written, so please do read it.
129
130	Some special forms introduced in Guix, such as the ‘substitute*’ macro, have
131	special indentation rules. These are defined in the .dir-locals.el file,
132	which Emacs automatically uses. If you do not use Emacs, please make sure to
133	let your editor know the rules.
134
135	We require all top-level procedures to carry a docstring. This requirement
136	can be relaxed for simple private procedures in the (guix build …) name space,
137	though.
138
139	Procedures should not have more than four positional parameters. Use keyword
140	parameters for procedures that take more than four parameters.
141
142	* Commit Access
143
144	For frequent contributors, having write access to the repository is
145	convenient. When you deem it necessary, feel free to ask for it on the
146	mailing list. When you get commit access, please make sure to follow the
147	policy below (discussions of the policy can take place on [email protected].)
148
149	Non-trivial patches should always be posted to [email protected] (trivial
150	patches include fixing typos, etc.)
151
152	For patches that just add a new package, and a simple one, it’s OK to commit,
153	if you’re confident (which means you successfully built it in a chroot setup,
154	and have done a reasonable copyright and license auditing.) Likewise for
155	package upgrades. We have a mailing list for commit notifications
156	([email protected]), so people can notice. Before pushing your changes,
157	make sure to run ‘git pull --rebase’.
158
159	For anything else, please post to [email protected] and leave time for a
160	review, without committing anything. If you didn’t receive any reply
161	after two weeks, and if you’re confident, it’s OK to commit.
162
163	That last part is subject to being adjusted, allowing individuals to commit
164	directly on non-controversial changes on parts they’re familiar with.