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.

217 lines
8.5 KiB

  1. @node Contributing
  2. @chapter Contributing
  3. This project is a cooperative effort, and we need your help to make it
  4. grow! Please get in touch with us on @email{} and
  5. @code{#guix} on the Freenode IRC network. We welcome ideas, bug
  6. reports, patches, and anything that may be helpful to the project. We
  7. particularly welcome help on packaging (@pxref{Packaging Guidelines}).
  8. @menu
  9. * Building from Git:: The latest and greatest.
  10. * Running Guix Before It Is Installed:: Hacker tricks.
  11. * The Perfect Setup:: The right tools.
  12. * Coding Style:: Hygiene of the contributor.
  13. * Submitting Patches:: Share your work.
  14. @end menu
  15. @node Building from Git
  16. @section Building from Git
  17. If you want to hack Guix itself, it is recommended to use the latest
  18. version from the Git repository. When building Guix from a checkout,
  19. the following packages are required in addition to those mentioned in
  20. the installation instructions (@pxref{Requirements}).
  21. @itemize
  22. @item @url{, GNU Autoconf};
  23. @item @url{, GNU Automake};
  24. @item @url{, GNU Gettext};
  25. @item @url{, Graphviz};
  26. @item @url{, GNU Help2man (optional)}.
  27. @end itemize
  28. Run @command{./bootstrap} to download the Nix daemon source code and to
  29. generate the build system infrastructure using autoconf. It reports an
  30. error if an inappropriate version of the above packages is being used.
  31. @noindent
  32. If you get an error like this one:
  33. @example
  34. error: possibly undefined macro: PKG_CHECK_MODULES
  35. @end example
  36. it probably means that Autoconf couldn’t find @file{pkg.m4}, which is
  37. provided by @command{pkg-config}. Make sure that @file{pkg.m4} is
  38. available. For instance, if you installed Automake in
  39. @file{/usr/local}, it wouldn’t look for @file{.m4} files in
  40. @file{/usr/share}. So you have to invoke the following command in that
  41. case
  42. @example
  43. export ACLOCAL_PATH=/usr/share/aclocal
  44. @end example
  45. See @pxref{Macro Search Path,,, automake, The GNU Automake Manual} for
  46. more information.
  47. Then, run @command{./configure} as usual.
  48. Finally, you have to invoke @code{make check} to run tests. If anything
  49. fails, take a look at installation instructions (@pxref{Installation})
  50. or send a message to the @email{, mailing list}.
  51. @node Running Guix Before It Is Installed
  52. @section Running Guix Before It Is Installed
  53. In order to keep a sane working environment, you will find it useful to
  54. test the changes made in your local source tree checkout without
  55. actually installing them. So that you can distinguish between your
  56. ``end-user'' hat and your ``motley'' costume.
  57. To that end, all the command-line tools can be used even if you have not
  58. run @code{make install}. To do that, prefix each command with
  59. @command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
  60. top build tree of Guix), as in:
  61. @example
  62. $ sudo ./pre-inst-env guix-daemon --build-users-group=guixbuild
  63. $ ./pre-inst-env guix build hello
  64. @end example
  65. @noindent
  66. Similarly, for a Guile session using the Guix modules:
  67. @example
  68. $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
  69. @end example
  70. The @command{pre-inst-env} script sets up all the environment variables
  71. necessary to support this, including @env{PATH} and @env{GUILE_LOAD_PATH}.
  72. @node The Perfect Setup
  73. @section The Perfect Setup
  74. The Perfect Setup to hack on Guix is basically the perfect setup used
  75. for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
  76. Manual}). First, you need more than an editor, you need
  77. @url{, Emacs}, empowered by the
  78. wonderful @url{, Geiser}.
  79. Geiser allows for interactive and incremental development from within
  80. Emacs: code compilation and evaluation from within buffers, access to
  81. on-line documentation (docstrings), context-sensitive completion,
  82. @kbd{M-.} to jump to an object definition, a REPL to try out your code,
  83. and more (@pxref{Introduction,,, geiser, Geiser User Manual}). For
  84. convenient Guix development, make sure to augment Guile’s load path so
  85. that it finds source files from your checkout:
  86. @lisp
  87. ;; @r{Assuming the Guix checkout is in ~/src/guix.}
  88. (add-to-list 'geiser-guile-load-path "~/src/guix")
  89. @end lisp
  90. To actually edit the code, Emacs already has a neat Scheme mode. But in
  91. addition to that, you must not miss
  92. @url{, Paredit}. It provides
  93. facilities to directly operate on the syntax tree, such as raising an
  94. s-expression or wrapping it, swallowing or rejecting the following
  95. s-expression, etc.
  96. @node Coding Style
  97. @section Coding Style
  98. In general our code follows the GNU Coding Standards (@pxref{Top,,,
  99. standards, GNU Coding Standards}). However, they do not say much about
  100. Scheme, so here are some additional rules.
  101. @menu
  102. * Programming Paradigm:: How to compose your elements.
  103. * Modules:: Where to store your code?
  104. * Data Types and Pattern Matching:: Implementing data structures.
  105. * Formatting Code:: Writing conventions.
  106. @end menu
  107. @node Programming Paradigm
  108. @subsection Programming Paradigm
  109. Scheme code in Guix is written in a purely functional style. One
  110. exception is code that involves input/output, and procedures that
  111. implement low-level concepts, such as the @code{memoize} procedure.
  112. @node Modules
  113. @subsection Modules
  114. Guile modules that are meant to be used on the builder side must live in
  115. the @code{(guix build @dots{})} name space. They must not refer to
  116. other Guix or GNU modules. However, it is OK for a ``host-side'' module
  117. to use a build-side module.
  118. Modules that deal with the broader GNU system should be in the
  119. @code{(gnu @dots{})} name space rather than @code{(guix @dots{})}.
  120. @node Data Types and Pattern Matching
  121. @subsection Data Types and Pattern Matching
  122. The tendency in classical Lisp is to use lists to represent everything,
  123. and then to browse them ``by hand'' using @code{car}, @code{cdr},
  124. @code{cadr}, and co. There are several problems with that style,
  125. notably the fact that it is hard to read, error-prone, and a hindrance
  126. to proper type error reports.
  127. Guix code should define appropriate data types (for instance, using
  128. @code{define-record-type*}) rather than abuse lists. In addition, it
  129. should use pattern matching, via Guile’s @code{(ice-9 match)} module,
  130. especially when matching lists.
  131. @node Formatting Code
  132. @subsection Formatting Code
  133. When writing Scheme code, we follow common wisdom among Scheme
  134. programmers. In general, we follow the
  135. @url{, Riastradh's Lisp
  136. Style Rules}. This document happens to describe the conventions mostly
  137. used in Guile’s code too. It is very thoughtful and well written, so
  138. please do read it.
  139. Some special forms introduced in Guix, such as the @code{substitute*}
  140. macro, have special indentation rules. These are defined in the
  141. @file{.dir-locals.el} file, which Emacs automatically uses. If you do
  142. not use Emacs, please make sure to let your editor know the rules.
  143. We require all top-level procedures to carry a docstring. This
  144. requirement can be relaxed for simple private procedures in the
  145. @code{(guix build @dots{})} name space, though.
  146. Procedures should not have more than four positional parameters. Use
  147. keyword parameters for procedures that take more than four parameters.
  148. @node Submitting Patches
  149. @section Submitting Patches
  150. Development is done using the Git distributed version control system.
  151. Thus, access to the repository is not strictly necessary. We welcome
  152. contributions in the form of patches as produced by @code{git
  153. format-patch} sent to the @email{, mailing list}.
  154. Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
  155. standards, GNU Coding Standards}); you can check the commit history for
  156. examples.
  157. Before submitting a patch that adds or modifies a package definition,
  158. please run @code{guix lint @var{package}}, where @var{package} is the
  159. name of the new or modified package, and fix any errors it reports
  160. (@pxref{Invoking guix lint}). In addition, please make sure the package
  161. builds on your platform, using @code{guix build @var{package}}. You may
  162. also want to check that dependent package (if applicable) are not
  163. affected by the change; @code{guix refresh --list-dependent
  164. @var{package}} will help you do that (@pxref{Invoking guix refresh}).
  165. When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as a
  166. subject. You may use your email client or the @command{git send-mail}
  167. command.