summaryrefslogtreecommitdiff
path: root/doc/contributing.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/contributing.texi')
-rw-r--r--doc/contributing.texi63
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