diff options
author | Maxim Cournoyer <maxim.cournoyer@gmail.com> | 2020-12-16 14:31:12 -0500 |
---|---|---|
committer | Maxim Cournoyer <maxim.cournoyer@gmail.com> | 2020-12-17 00:51:49 -0500 |
commit | 15fba3b13d543bbc1f13907e659c354a5b6f28ec (patch) | |
tree | 515585cf073460ee317193b06af500eba5080763 | |
parent | b97a533a485461e7e554fdd2395df99c213b5429 (diff) |
doc: Add Emacs packaging guidelines.
* doc/contributing.texi (Emacs Packages): New subsection.
-rw-r--r-- | doc/contributing.texi | 41 | ||||
-rw-r--r-- | doc/guix.texi | 1 |
2 files changed, 42 insertions, 0 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 78d9990b30..6500bfa3a1 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -391,6 +391,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 +637,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 are 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 diff --git a/doc/guix.texi b/doc/guix.texi index 38927bc0b5..392baf5910 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -7930,6 +7930,7 @@ Which D compiler is used can be specified with the @code{#:ldc} parameter which defaults to @code{ldc}. @end defvr +@anchor{emacs-build-system} @defvr {Scheme Variable} emacs-build-system This variable is exported by @code{(guix build-system emacs)}. It implements an installation procedure similar to the packaging system |