Mirror of GNU Guix
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

166 lines
7.2 KiB

  1. -*- mode: org; coding: utf-8; -*-
  2. #+TITLE: Hacking GNU Guix and Its Incredible Distro
  3. Copyright © 2012, 2013 Ludovic Courtès <ludo@gnu.org>
  4. Copyright © 2013 Nikita Karetnikov <nikita@karetnikov.org>
  5. Copying and distribution of this file, with or without modification,
  6. are permitted in any medium without royalty provided the copyright
  7. notice and this notice are preserved.
  8. * Building from Git
  9. When building Guix from a checkout, the following packages are required in
  10. addition to those mentioned in the installation instructions:
  11. - [[http://www.gnu.org/software/autoconf/][GNU Autoconf]]
  12. - [[http://www.gnu.org/software/automake/][GNU Automake]]
  13. - [[http://www.gnu.org/software/gettext/][GNU Gettext]]
  14. - [[http://www.graphviz.org/][Graphviz]]
  15. Run ‘./bootstrap’ to download the Nix daemon source code and to generate the
  16. build system infrastructure using autoconf. It reports an error if an
  17. inappropriate version of the above packages is being used.
  18. The ‘bootstrap’ script, among other things, invokes ‘git submodule update’; if
  19. you didn’t run it, you may get the following error:
  20. make: *** No rule to make target `nix/libstore/schema.sql', needed by
  21. `nix/libstore/schema.sql.hh'
  22. If you get an error like this one:
  23. configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
  24. it probably means that Autoconf couldn’t find ‘pkg.m4’, which is provided by
  25. pkg-config. Make sure that ‘pkg.m4’ is available. For instance, if you
  26. installed Automake in ‘/usr/local’, it wouldn’t look for ‘.m4’ files in
  27. ‘/usr/share’. So you have to invoke the following command in that case
  28. $ export ACLOCAL_PATH=/usr/share/aclocal
  29. See “info '(automake) Macro Search Path'” for more information.
  30. Then, run ‘./configure’ as usual.
  31. Finally, you have to invoke ‘make check’ to run tests. If anything fails,
  32. take a look at “info '(guix) Installation'” or send a message to
  33. <guix-devel@gnu.org>.
  34. * Running Guix before it is installed
  35. Command-line tools can be used even if you have not run "make install".
  36. To do that, prefix each command with ‘./pre-inst-env’, as in:
  37. ./pre-inst-env guix build --help
  38. Similarly, for a Guile session using the Guix modules:
  39. ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
  40. The ‘pre-inst-env’ script sets up all the environment variables
  41. necessary to support this.
  42. * The Perfect Setup
  43. The Perfect Setup to hack on Guix is basically the perfect setup used
  44. for Guile hacking (info "(guile) Using Guile in Emacs"). First, you
  45. need more than an editor, you need [[http://www.gnu.org/software/emacs][Emacs]], empowered by the wonderful
  46. [[http://nongnu.org/geiser/][Geiser]].
  47. Geiser allows for interactive and incremental development from within
  48. Emacs: code compilation and evaluation from within buffers, access to
  49. on-line documentation (docstrings), context-sensitive completion, M-. to
  50. jump to an object definition, a REPL to try out your code, and more.
  51. To actually edit the code, Emacs already has a neat Scheme mode. But in
  52. addition to that, you must not miss [[http://www.emacswiki.org/emacs/ParEdit][Paredit]]. It provides facilities to
  53. directly operate on the syntax tree, such as raising an s-expression or
  54. wrapping it, swallowing or rejecting the following s-expression, etc.
  55. * Submitting Patches
  56. Development is done using the Git distributed version control system. Thus,
  57. access to the repository is not strictly necessary. We welcome contributions
  58. in the form of patches as produced by ‘git format-patch’ sent to
  59. guix-devel@gnu.org. Please write commit logs in the [[http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs][GNU ChangeLog format]].
  60. As you become a regular contributor, you may find it convenient to have write
  61. access to the repository (see below.)
  62. * Coding Style
  63. In general our code follows the [[info:standards][GNU Coding Standards]] (GCS). However, the GCS
  64. do not say much about Scheme, so here are some additional rules.
  65. ** Programming Paradigm
  66. Scheme code in Guix is written in a purely functional style. One exception is
  67. code that involves input/output, and procedures that implement low-level
  68. concepts, such as the ‘memoize’ procedure.
  69. ** Modules
  70. Guile modules that are meant to be used on the builder side must live in the
  71. (guix build …) name space. They must not refer to other Guix or GNU modules.
  72. However, it is OK for a “host-side” module to use a build-side module.
  73. Modules that deal with the broader GNU system should be in the (gnu …) name
  74. space rather than (guix …).
  75. ** Data Types and Pattern Matching
  76. The tendency in classical Lisp is to use lists to represent everything, and
  77. then to browse them “by hand” using ‘car’, ‘cdr’, ‘cadr’, and co. There are
  78. several problems with that style, notably the fact that it is hard to read,
  79. error-prone, and a hindrance to proper type error reports.
  80. Guix code should define appropriate data types (for instance, using
  81. ‘define-record-type*’) rather than abuse lists. In addition, it should use
  82. pattern matching, via Guile’s (ice-9 match) module, especially when matching
  83. lists.
  84. ** Formatting Code
  85. When writing Scheme code, we follow common wisdom among Scheme programmers.
  86. In general, we follow the [[http://mumble.net/~campbell/scheme/style.txt][Riastradh's Lisp Style Rules]]. This document happens
  87. to describe the conventions mostly used in Guile’s code too. It is very
  88. thoughtful and well written, so please do read it.
  89. Some special forms introduced in Guix, such as the ‘substitute*’ macro, have
  90. special indentation rules. These are defined in the .dir-locals.el file,
  91. which Emacs automatically uses. If you do not use Emacs, please make sure to
  92. let your editor know the rules.
  93. We require all top-level procedures to carry a docstring. This requirement
  94. can be relaxed for simple private procedures in the (guix build …) name space,
  95. though.
  96. Procedures should not have more than four positional parameters. Use keyword
  97. parameters for procedures that take more than four parameters.
  98. * Commit Access
  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 guix-devel@gnu.org.)
  103. Non-trivial patches should always be posted to guix-devel@gnu.org (trivial
  104. patches include fixing typos, etc.)
  105. For patches that just add a new package, and a simple one, it’s OK to commit,
  106. if you’re confident (which means you successfully built it in a chroot setup,
  107. and have done a reasonable copyright and license auditing.) Likewise for
  108. package upgrades. We have a mailing list for commit notifications
  109. (guix-commits@gnu.org), so people can notice. Before pushing your changes,
  110. make sure to run ‘git pull --rebase’.
  111. For anything else, please post to guix-devel@gnu.org and leave time for a
  112. review, without committing anything. If you didn’t receive any reply
  113. after two weeks, and if you’re confident, it’s OK to commit.
  114. That last part is subject to being adjusted, allowing individuals to commit
  115. directly on non-controversial changes on parts they’re familiar with.