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.

321 lines
12 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. @cindex code of conduct, of contributors
  9. @cindex contributor covenant
  10. We want to provide a warm, friendly, and harassment-free environment, so
  11. that anyone can contribute to the best of their abilities. To this end
  12. our project uses a ``Contributor Covenant'', which was adapted from
  13. @url{}. You can find a local version in
  14. the @file{CODE-OF-CONDUCT} file in the source tree.
  15. @menu
  16. * Building from Git:: The latest and greatest.
  17. * Running Guix Before It Is Installed:: Hacker tricks.
  18. * The Perfect Setup:: The right tools.
  19. * Coding Style:: Hygiene of the contributor.
  20. * Submitting Patches:: Share your work.
  21. @end menu
  22. @node Building from Git
  23. @section Building from Git
  24. If you want to hack Guix itself, it is recommended to use the latest
  25. version from the Git repository. When building Guix from a checkout,
  26. the following packages are required in addition to those mentioned in
  27. the installation instructions (@pxref{Requirements}).
  28. @itemize
  29. @item @url{, GNU Autoconf};
  30. @item @url{, GNU Automake};
  31. @item @url{, GNU Gettext};
  32. @item @url{, GNU Texinfo};
  33. @item @url{, Graphviz};
  34. @item @url{, GNU Help2man (optional)}.
  35. @end itemize
  36. The easiest way to set up a development environment for Guix is, of
  37. course, by using Guix! The following command starts a new shell where
  38. all the dependencies and appropriate environment variables are set up to
  39. hack on Guix:
  40. @example
  41. guix environment guix
  42. @end example
  43. @xref{Invoking guix environment}, for more information on that command.
  44. Extra dependencies can be added with @option{--ad-hoc}:
  45. @example
  46. guix environment guix --ad-hoc help2man git strace
  47. @end example
  48. Run @command{./bootstrap} to generate the build system infrastructure
  49. using Autoconf and Automake. If you get an error like this one:
  50. @example
  51. error: possibly undefined macro: PKG_CHECK_MODULES
  52. @end example
  53. @noindent
  54. it probably means that Autoconf couldn’t find @file{pkg.m4}, which is
  55. provided by pkg-config. Make sure that @file{pkg.m4} is available. The
  56. same holds for the @file{guile.m4} set of macros provided by Guile. For
  57. instance, if you installed Automake in @file{/usr/local}, it wouldn’t
  58. look for @file{.m4} files in @file{/usr/share}. In that case, you have
  59. to invoke the following command:
  60. @example
  61. export ACLOCAL_PATH=/usr/share/aclocal
  62. @end example
  63. @xref{Macro Search Path,,, automake, The GNU Automake Manual}, for
  64. more information.
  65. Then, run @command{./configure} as usual.
  66. Finally, you have to invoke @code{make check} to run tests. If anything
  67. fails, take a look at installation instructions (@pxref{Installation})
  68. or send a message to the @email{, mailing list}.
  69. @node Running Guix Before It Is Installed
  70. @section Running Guix Before It Is Installed
  71. In order to keep a sane working environment, you will find it useful to
  72. test the changes made in your local source tree checkout without
  73. actually installing them. So that you can distinguish between your
  74. ``end-user'' hat and your ``motley'' costume.
  75. To that end, all the command-line tools can be used even if you have not
  76. run @code{make install}. To do that, prefix each command with
  77. @command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
  78. top build tree of Guix), as in:
  79. @example
  80. $ sudo ./pre-inst-env guix-daemon --build-users-group=guixbuild
  81. $ ./pre-inst-env guix build hello
  82. @end example
  83. @noindent
  84. Similarly, for a Guile session using the Guix modules:
  85. @example
  86. $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
  87. ;;; ("x86_64-linux")
  88. @end example
  89. @noindent
  90. @cindex REPL
  91. @cindex read-eval-print loop
  92. @dots{} and for a REPL (@pxref{Using Guile Interactively,,, guile, Guile
  93. Reference Manual}):
  94. @example
  95. $ ./pre-inst-env guile
  96. scheme@@(guile-user)> ,use(guix)
  97. scheme@@(guile-user)> ,use(gnu)
  98. scheme@@(guile-user)> (define snakes
  99. (fold-packages
  100. (lambda (package lst)
  101. (if (string-prefix? "python"
  102. (package-name package))
  103. (cons package lst)
  104. lst))
  105. '()))
  106. scheme@@(guile-user)> (length snakes)
  107. $1 = 361
  108. @end example
  109. The @command{pre-inst-env} script sets up all the environment variables
  110. necessary to support this, including @env{PATH} and @env{GUILE_LOAD_PATH}.
  111. Note that @command{./pre-inst-env guix pull} does @emph{not} upgrade the
  112. local source tree; it simply updates the @file{~/.config/guix/latest}
  113. symlink (@pxref{Invoking guix pull}). Run @command{git pull} instead if
  114. you want to upgrade your local source tree.
  115. @node The Perfect Setup
  116. @section The Perfect Setup
  117. The Perfect Setup to hack on Guix is basically the perfect setup used
  118. for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
  119. Manual}). First, you need more than an editor, you need
  120. @url{, Emacs}, empowered by the
  121. wonderful @url{, Geiser}.
  122. Geiser allows for interactive and incremental development from within
  123. Emacs: code compilation and evaluation from within buffers, access to
  124. on-line documentation (docstrings), context-sensitive completion,
  125. @kbd{M-.} to jump to an object definition, a REPL to try out your code,
  126. and more (@pxref{Introduction,,, geiser, Geiser User Manual}). For
  127. convenient Guix development, make sure to augment Guile’s load path so
  128. that it finds source files from your checkout:
  129. @lisp
  130. ;; @r{Assuming the Guix checkout is in ~/src/guix.}
  131. (with-eval-after-load 'geiser-guile
  132. (add-to-list 'geiser-guile-load-path "~/src/guix"))
  133. @end lisp
  134. To actually edit the code, Emacs already has a neat Scheme mode. But in
  135. addition to that, you must not miss
  136. @url{, Paredit}. It provides
  137. facilities to directly operate on the syntax tree, such as raising an
  138. s-expression or wrapping it, swallowing or rejecting the following
  139. s-expression, etc.
  140. GNU Guix also comes with a minor mode that provides some additional
  141. functionality for Scheme buffers (@pxref{Emacs Development}).
  142. @node Coding Style
  143. @section Coding Style
  144. In general our code follows the GNU Coding Standards (@pxref{Top,,,
  145. standards, GNU Coding Standards}). However, they do not say much about
  146. Scheme, so here are some additional rules.
  147. @menu
  148. * Programming Paradigm:: How to compose your elements.
  149. * Modules:: Where to store your code?
  150. * Data Types and Pattern Matching:: Implementing data structures.
  151. * Formatting Code:: Writing conventions.
  152. @end menu
  153. @node Programming Paradigm
  154. @subsection Programming Paradigm
  155. Scheme code in Guix is written in a purely functional style. One
  156. exception is code that involves input/output, and procedures that
  157. implement low-level concepts, such as the @code{memoize} procedure.
  158. @node Modules
  159. @subsection Modules
  160. Guile modules that are meant to be used on the builder side must live in
  161. the @code{(guix build @dots{})} name space. They must not refer to
  162. other Guix or GNU modules. However, it is OK for a ``host-side'' module
  163. to use a build-side module.
  164. Modules that deal with the broader GNU system should be in the
  165. @code{(gnu @dots{})} name space rather than @code{(guix @dots{})}.
  166. @node Data Types and Pattern Matching
  167. @subsection Data Types and Pattern Matching
  168. The tendency in classical Lisp is to use lists to represent everything,
  169. and then to browse them ``by hand'' using @code{car}, @code{cdr},
  170. @code{cadr}, and co. There are several problems with that style,
  171. notably the fact that it is hard to read, error-prone, and a hindrance
  172. to proper type error reports.
  173. Guix code should define appropriate data types (for instance, using
  174. @code{define-record-type*}) rather than abuse lists. In addition, it
  175. should use pattern matching, via Guile’s @code{(ice-9 match)} module,
  176. especially when matching lists.
  177. @node Formatting Code
  178. @subsection Formatting Code
  179. When writing Scheme code, we follow common wisdom among Scheme
  180. programmers. In general, we follow the
  181. @url{, Riastradh's Lisp
  182. Style Rules}. This document happens to describe the conventions mostly
  183. used in Guile’s code too. It is very thoughtful and well written, so
  184. please do read it.
  185. Some special forms introduced in Guix, such as the @code{substitute*}
  186. macro, have special indentation rules. These are defined in the
  187. @file{.dir-locals.el} file, which Emacs automatically uses. If you do
  188. not use Emacs, please make sure to let your editor know the rules.
  189. We require all top-level procedures to carry a docstring. This
  190. requirement can be relaxed for simple private procedures in the
  191. @code{(guix build @dots{})} name space, though.
  192. Procedures should not have more than four positional parameters. Use
  193. keyword parameters for procedures that take more than four parameters.
  194. @node Submitting Patches
  195. @section Submitting Patches
  196. Development is done using the Git distributed version control system.
  197. Thus, access to the repository is not strictly necessary. We welcome
  198. contributions in the form of patches as produced by @code{git
  199. format-patch} sent to the @email{, mailing list}.
  200. Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
  201. standards, GNU Coding Standards}); you can check the commit history for
  202. examples.
  203. Before submitting a patch that adds or modifies a package definition,
  204. please run through this check list:
  205. @enumerate
  206. @item
  207. Take some time to provide an adequate synopsis and description for the
  208. package. @xref{Synopses and Descriptions}, for some guidelines.
  209. @item
  210. Run @code{guix lint @var{package}}, where @var{package} is the
  211. name of the new or modified package, and fix any errors it reports
  212. (@pxref{Invoking guix lint}).
  213. @item
  214. Make sure the package builds on your platform, using @code{guix build
  215. @var{package}}.
  216. @item
  217. Take a look at the profile reported by @command{guix size}
  218. (@pxref{Invoking guix size}). This will allow you to notice references
  219. to other packages unwillingly retained. It may also help determine
  220. whether to split the package (@pxref{Packages with Multiple Outputs}),
  221. and which optional dependencies should be used.
  222. @item
  223. For important changes, check that dependent package (if applicable) are
  224. not affected by the change; @code{guix refresh --list-dependent
  225. @var{package}} will help you do that (@pxref{Invoking guix refresh}).
  226. @item
  227. @cindex determinism, of build processes
  228. @cindex reproducible builds, checking
  229. Check whether the package's build process is deterministic. This
  230. typically means checking whether an independent build of the package
  231. yields the exact same result that you obtained, bit for bit.
  232. A simple way to do that is by building the same package several times in
  233. a row on your machine (@pxref{Invoking guix build}):
  234. @example
  235. guix build --rounds=2 my-package
  236. @end example
  237. This is enough to catch a class of common non-determinism issues, such
  238. as timestamps or randomly-generated output in the build result.
  239. Another option is to use @command{guix challenge} (@pxref{Invoking guix
  240. challenge}). You may run it once the package has been committed and
  241. built by @code{} to check whether it obtains the same
  242. result as you did. Better yet: Find another machine that can build it
  243. and run @command{guix publish}. Since the remote build machine is
  244. likely different from yours, this can catch non-determinism issues
  245. related to the hardware---e.g., use of different instruction set
  246. extensions---or to the operating system kernel---e.g., reliance on
  247. @code{uname} or @file{/proc} files.
  248. @end enumerate
  249. When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as a
  250. subject. You may use your email client or the @command{git send-mail}
  251. command.