From f06f569aa27ff0642948c8bb6fcca78807046f3d Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Mon, 14 Dec 2020 12:19:05 +0100 Subject: doc: Link to "Pattern Matching" in Guile. * doc/contributing.texi (Data Types and Pattern Matching): Link to the "Pattern Matching" node of the Guile manual. --- doc/contributing.texi | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'doc/contributing.texi') diff --git a/doc/contributing.texi b/doc/contributing.texi index d8de71055a..866d2dae6b 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -864,7 +864,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 -- cgit 1.4.1 From 48cccf06ad84f96bb4fc839ab6f26525c7e8dae0 Mon Sep 17 00:00:00 2001 From: Tobias Geerinckx-Rice Date: Mon, 14 Dec 2020 19:08:20 +0100 Subject: doc: Note different texlive-tiny & texline-union natures. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/contributing.texi (Submitting Patches): Add ‘package’ and ‘procedure’. Inspired-by: Jorge P. de Morais Neto --- doc/contributing.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/contributing.texi') diff --git a/doc/contributing.texi b/doc/contributing.texi index 866d2dae6b..78d9990b30 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1009,7 +1009,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 -- cgit 1.4.1 From 15fba3b13d543bbc1f13907e659c354a5b6f28ec Mon Sep 17 00:00:00 2001 From: Maxim Cournoyer Date: Wed, 16 Dec 2020 14:31:12 -0500 Subject: doc: Add Emacs packaging guidelines. * doc/contributing.texi (Emacs Packages): New subsection. --- doc/contributing.texi | 41 +++++++++++++++++++++++++++++++++++++++++ doc/guix.texi | 1 + 2 files changed, 42 insertions(+) (limited to 'doc/contributing.texi') 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 -- cgit 1.4.1 From eea7cc3185282b494a964eee4d6b3554f8eda0aa Mon Sep 17 00:00:00 2001 From: Nicolas Goaziou Date: Thu, 17 Dec 2020 10:01:47 +0100 Subject: doc: Emacs Packages: Fix typos. * doc/contributing.texi (Emacs Packages): Fix typo. Also remove spurious white space, and unnecessary quote. --- doc/contributing.texi | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc/contributing.texi') diff --git a/doc/contributing.texi b/doc/contributing.texi index 6500bfa3a1..4195cb4105 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -645,14 +645,14 @@ more information (@pxref{origin Reference}). 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 +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 +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. +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 -- cgit 1.4.1