unofficial mirror of guix-devel@gnu.org 
 help / color / mirror / code / Atom feed
blob 1fb65f8e114ee19acbdcf99c6360b709bdf79603 10461 bytes (raw)
name: HACKING 	 # note: path name is non-authoritative(*)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
-*- mode: org; coding: utf-8; -*-

#+TITLE: Hacking GNU Guix and Its Incredible Distro

Copyright © 2012, 2013 Ludovic Courtès <ludo@gnu.org>
Copyright © 2013 Nikita Karetnikov <nikita@karetnikov.org>
Copyright © 2014 Pierre-Antoine Rault <par@rigelk.eu>

  Copying and distribution of this file, with or without modification,
  are permitted in any medium without royalty provided the copyright
  notice and this notice are preserved.


* Building from Git

Development should be done through git. When building Guix from a git
checkout, the following packages are required in addition to those
mentioned in the installation instructions:

  - [[http://www.gnu.org/software/autoconf/][GNU Autoconf]]
  - [[http://www.gnu.org/software/automake/][GNU Automake]]
  - [[http://www.gnu.org/software/gettext/][GNU Gettext]]
  - [[http://www.graphviz.org/][Graphviz]]

Run ‘./bootstrap’ to download the Nix daemon source code and to generate the
build system infrastructure using autoconf.  It reports an error if an
inappropriate version of the above packages is being used.

The ‘bootstrap’ script, among other things, invokes ‘git submodule update’; if
you didn’t run it, you may get the following error:

  make: *** No rule to make target `nix/libstore/schema.sql', needed by
  `nix/libstore/schema.sql.hh'

If you get an error like this one:

  configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES

it probably means that Autoconf couldn’t find ‘pkg.m4’, which is provided by
pkg-config.  Make sure that ‘pkg.m4’ is available.  For instance, if you
installed Automake in ‘/usr/local’, it wouldn’t look for ‘.m4’ files in
‘/usr/share’.  So you have to invoke the following command in that case

  $ export ACLOCAL_PATH=/usr/share/aclocal

See “info '(automake) Macro Search Path'” for more information.

Then, run ‘./configure’ as usual.

Finally, you have to invoke ‘make check’ to run tests.  If anything fails,
take a look at “info '(guix) Installation'” or send a message to
<guix-devel@gnu.org>.

* Running Guix before it is installed

Command-line tools can be used even if you have not run "make
install". Actually, some developpers prefer not to run make install and
use a script in their /usr/local/bin/ named 'guix' to call the following
substitute to 'guix'. 

To do that, prefix each command with ‘./pre-inst-env’, as in:

  ./pre-inst-env guix build --help

Similarly, for a Guile session using the Guix modules:

  ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'

The ‘pre-inst-env’ script sets up all the environment variables
necessary to support this.

* The Perfect Setup

The Perfect Setup to hack on Guix is basically the perfect setup used
for Guile hacking (info "(guile) Using Guile in Emacs").  First, you
need more than an editor, you need [[http://www.gnu.org/software/emacs][Emacs]], empowered by the wonderful
[[http://nongnu.org/geiser/][Geiser]].

Geiser allows for interactive and incremental development from within
Emacs: code compilation and evaluation from within buffers, access to
on-line documentation (docstrings), context-sensitive completion, M-. to
jump to an object definition, a REPL to try out your code, and more.

To actually edit the code, Emacs already has a neat Scheme mode.  But in
addition to that, you must not miss [[http://www.emacswiki.org/emacs/ParEdit][Paredit]].  It provides facilities to
directly operate on the syntax tree, such as raising an s-expression or
wrapping it, swallowing or rejecting the following s-expression, etc.

* Submitting Patches

Development is done using the Git distributed version control system.  Thus,
access to the repository is not strictly necessary.  We welcome contributions
in the form of patches as produced by ‘git format-patch’ sent to
guix-devel@gnu.org (see below). Remember to please write commit logs in
the [[http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs][GNU ChangeLog format]].

When posting a patch to the mailing-list, use "[PATCH] ..." as a
subject. You may use your email client or the 'git send-mail' command.

Depending on your distribution, 'git send-mail' might be part of another
package (git-email in Debian, for instance). It is an extremely nice
tool. You can generate a patch series by doing:

$ git format-patch <commit>

This will generate a bunch of files called 0001-commit-title, 
0002-commit-title and so on. Then just do:

$ git send-email --to guix-devel@gnu.org --in-reply-to <message-id of 
your first message> 000*.patch

And we'll get all your patches in a nice thread :)

As you become a regular contributor, you may find it convenient to have write
access to the repository (see below, Commit Access.)

* Packaging 101

To get started adding package to the guix tree (gnu/packages/), copy
a *.scm in the tree or create a new one. It should contain at least three
elements:

  - A licence (copy from other .scm, and put your name)
  - A define-module form (which imports (and may export) modules)
  - A define-public form containing the package description (one may use
    define only, but then has to add an #:export (package_name) to the
    define form - deprecated)

Modify the define-public form according to the package: copyright, module
name and name (both lower case), version, uri, description (add two spaces at the end of line),
license (see guix/licenses.scm), synopsis (shouldn't repeat the package
name), home page.

Use 'guix download <uri>' to download the package, and print its hash in
base32. Modify the hash in the sha256 form accordingly. Note that <uri>
can be a direct http:// adress or a mirror://xxx/... (where xxx is either
gnu, sourceforge, savannah, cpan, kernel.org, gnome, apache, xorg, or
imagemagick). Check with gpg or hash that the downloaded package is the
good one ;)

Your package may have dependencies. Sort them between those needed to
only compile (that is, only to build the program), and those needed by
the program itself (that is, when the end user runs it). The former are
called 'native-inputs', the latter 'inputs'. When building a binary, both
will be needed on the system, but it avoids a end user to have to download
native-inputs if he downloads a binary of the package.

Once your file is done, double check its syntax. If it has errors
(i.e: unclosed parentheses, forgotten export/defin-public method), it
won't show with the command 'guix package -A' (add name to just output
your package. If it shows, well done, you may proceed to the next step:
building your package.

Don't forget to use 'guix build -c', as -c will make use of all your cores.

If the build shows errors, try passing configure flags and check inputs. Use the
argument -K to keep /tmp folder even after a build fail, as it may
contain info on how to solve the issue.

Your package has built successfuly ? Consider talking about it with other
guix devs and submitting a patch. (see previous section)

* Coding Style

In general our code follows the [[info:standards][GNU Coding Standards]] (GCS).  However, the GCS
do not say much about Scheme, so here are some additional rules.

** Programming Paradigm

Scheme code in Guix is written in a purely functional style.  One exception is
code that involves input/output, and procedures that implement low-level
concepts, such as the ‘memoize’ procedure.

** Modules

Guile modules that are meant to be used on the builder side must live in the
(guix build …) name space.  They must not refer to other Guix or GNU modules.
However, it is OK for a “host-side” module to use a build-side module.

Modules that deal with the broader GNU system should be in the (gnu …) name
space rather than (guix …).

** Data Types and Pattern Matching

The tendency in classical Lisp is to use lists to represent everything, and
then to browse them “by hand” using ‘car’, ‘cdr’, ‘cadr’, and co.  There are
several problems with that style, notably the fact that it is hard to read,
error-prone, and a hindrance to proper type error reports.

Guix code should define appropriate data types (for instance, using
‘define-record-type*’) rather than abuse lists.  In addition, it should use
pattern matching, via Guile’s (ice-9 match) module, especially when matching
lists.

** Formatting Code

When writing Scheme code, we follow common wisdom among Scheme programmers.
In general, we follow the [[http://mumble.net/~campbell/scheme/style.txt][Riastradh's Lisp Style Rules]].  This document happens
to describe the conventions mostly used in Guile’s code too.  It is very
thoughtful and well written, so please do read it.

Some special forms introduced in Guix, such as the ‘substitute*’ macro, have
special indentation rules.  These are defined in the .dir-locals.el file,
which Emacs automatically uses.  If you do not use Emacs, please make sure to
let your editor know the rules.

We require all top-level procedures to carry a docstring.  This requirement
can be relaxed for simple private procedures in the (guix build …) name space,
though.

Procedures should not have more than four positional parameters.  Use keyword
parameters for procedures that take more than four parameters.

* Commit Access

For frequent contributors, having write access to the repository is
convenient.  When you deem it necessary, feel free to ask for it on the
mailing list.  When you get commit access, please make sure to follow the
policy below (discussions of the policy can take place on guix-devel@gnu.org.)

Non-trivial patches should always be posted to guix-devel@gnu.org (trivial
patches include fixing typos, etc.)

For patches that just add a new package, and a simple one, it’s OK to commit,
if you’re confident (which means you successfully built it in a chroot setup,
and have done a reasonable copyright and license auditing.)  Likewise for
package upgrades.  We have a mailing list for commit notifications
(guix-commits@gnu.org), so people can notice.  Before pushing your changes,
make sure to run ‘git pull --rebase’.

For anything else, please post to guix-devel@gnu.org and leave time for a
review, without committing anything.  If you didn’t receive any reply
after two weeks, and if you’re confident, it’s OK to commit.

That last part is subject to being adjusted, allowing individuals to commit
directly on non-controversial changes on parts they’re familiar with.

debug log:

solving 1fb65f8 ...
found 1fb65f8 in https://yhetil.org/guix-devel/531C9AE3.8090402@rigelk.eu/
found 0dc2908 in https://git.savannah.gnu.org/cgit/guix.git
preparing index
index prepared:
100644 0dc290831829028ddf2e78577fbd1914407da0c8	HACKING

applying [1/1] https://yhetil.org/guix-devel/531C9AE3.8090402@rigelk.eu/
diff --git a/HACKING b/HACKING
index 0dc2908..1fb65f8 100644

1:33: trailing whitespace.
substitute to 'guix'. 
1:55: trailing whitespace.
This will generate a bunch of files called 0001-commit-title, 
1:58: trailing whitespace.
$ git send-email --to guix-devel@gnu.org --in-reply-to <message-id of 
Checking patch HACKING...
Applied patch HACKING cleanly.
warning: 3 lines add whitespace errors.

index at:
100644 1fb65f8e114ee19acbdcf99c6360b709bdf79603	HACKING

(*) Git path names are given by the tree(s) the blob belongs to.
    Blobs themselves have no identifier aside from the hash of its contents.^

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/guix.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).