diff options
Diffstat (limited to 'doc/contributing.texi')
| -rw-r--r-- | doc/contributing.texi | 63 |
1 files changed, 53 insertions, 10 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index d8de71055a..d0ab08336a 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -166,14 +166,15 @@ actually installing them. So that you can distinguish between your ``end-user'' hat and your ``motley'' costume. To that end, all the command-line tools can be used even if you have not -run @code{make install}. To do that, you first need to have an environment -with all the dependencies available (@pxref{Building from Git}), and then -simply prefix each command with -@command{./pre-inst-env} (the @file{pre-inst-env} script lives in the -top build tree of Guix; it is generated by @command{./configure}). -As an example, here is how you would build the @code{hello} package as -defined in your working tree (this assumes @command{guix-daemon} is -already running on your system; it's OK if it's a different version): +run @code{make install}. To do that, you first need to have an +environment with all the dependencies available (@pxref{Building from +Git}), and then simply prefix each command with @command{./pre-inst-env} +(the @file{pre-inst-env} script lives in the top build tree of Guix; it +is generated by running @command{./bootstrap} followed by +@command{./configure}). As an example, here is how you would build the +@code{hello} package as defined in your working tree (this assumes +@command{guix-daemon} is already running on your system; it's OK if it's +a different version): @example $ ./pre-inst-env guix build hello @@ -391,6 +392,7 @@ needed is to review and apply the patch. * Version Numbers:: When the name is not enough. * Synopses and Descriptions:: Helping users find the right package. * Snippets versus Phases:: Whether to use a snippet, or a build phase. +* Emacs Packages:: Your Elisp fix. * Python Modules:: A touch of British comedy. * Perl Modules:: Little pearls. * Java Packages:: Coffee break. @@ -636,6 +638,46 @@ embed store items in the sources; such patching should rather be done using build phases. Refer to the @code{origin} record documentation for more information (@pxref{origin Reference}). +@node Emacs Packages +@subsection Emacs Packages + +@cindex emacs, packaging +@cindex elisp, packaging +Emacs packages should preferably use the Emacs build system +(@pxref{emacs-build-system}), for uniformity and the benefits provided +by its build phases, such as the auto-generation of the autoloads file +and the byte compilation of the sources. Because there is no +standardized way to run a test suite for Emacs packages, tests are +disabled by default. When a test suite is available, it should be +enabled by setting the @code{#:tests?} argument to @code{#true}. By +default, the command to run the test is @command{make check}, but any +command can be specified via the @code{#:test-command} argument. The +@code{#:test-command} argument expects a list containing a command and +its arguments, to be invoked during the @code{check} phase. + +The Elisp dependencies of Emacs packages are typically provided as +@code{propagated-inputs} when required at run time. As for other +packages, build or test dependencies should be specified as +@code{native-inputs}. + +Emacs packages sometimes depend on resources directories that should be +installed along the Elisp files. The @code{#:include} argument can be +used for that purpose, by specifying a list of regexps to match. The +best practice when using the @code{#:include} argument is to extend +rather than override its default value (accessible via the +@code{%default-include} variable). As an example, a yasnippet extension +package typically include a @file{snippets} directory, which could be +copied to the installation directory using: + +@lisp +#:include (cons "^snippets/" %default-include)) +@end lisp + +When encountering problems, it is wise to check for the presence of the +@code{Package-Requires} extension header in the package main source +file, and whether any dependencies and their versions listed therein are +satisfied. + @node Python Modules @subsection Python Modules @@ -864,7 +906,8 @@ to proper type error reports. Guix code should define appropriate data types (for instance, using @code{define-record-type*}) rather than abuse lists. In addition, it should use pattern matching, via Guile’s @code{(ice-9 match)} module, -especially when matching lists. +especially when matching lists (@pxref{Pattern Matching,,, guile, GNU +Guile Reference Manual}). @node Formatting Code @subsection Formatting Code @@ -1008,7 +1051,7 @@ to other packages unwillingly retained. It may also help determine whether to split the package (@pxref{Packages with Multiple Outputs}), and which optional dependencies should be used. In particular, avoid adding @code{texlive} as a dependency: because of its extreme size, use -@code{texlive-tiny} or @code{texlive-union} instead. +the @code{texlive-tiny} package or @code{texlive-union} procedure instead. @item For important changes, check that dependent package (if applicable) are |