``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
* 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.
appropriately.
Synopses and descriptions are translated by volunteers
-@uref{https://translationproject.org/domain/guix-packages.html, at the
-Translation Project} so that as many users as possible can read them in
+@uref{https://translate.fedoraproject.org/projects/guix/packages, at
+Weblate} so that as many users as possible can read them in
their native language. User interfaces search them and display them in
the language specified by the current locale.
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
dashes should remain in place.
In the rust ecosystem it is common for multiple incompatible versions of a
-package to be used at any given time, so all packages should have a versioned
-suffix. If a package has passed version 1.0.0 then just the major version
-number is sufficient (e.g.@: @code{rust-clap-2}), otherwise the version suffix
-should contain both the major and minor version (e.g.@: @code{rust-rand-0.6}).
+package to be used at any given time, so all package definitions should have a
+versioned suffix. The versioned suffix is the left-most non-zero digit (and
+any leading zeros, of course). This follows the ``caret'' version scheme
+intended by Cargo. Examples@: @code{rust-clap-2}, @code{rust-rand-0.6}.
Because of the difficulty in reusing rust packages as pre-compiled inputs for
other packages the Cargo build system (@pxref{Build Systems,
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
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
before they hit users, and to reduce the window during which pre-built
binaries are not available.
-Generally, branches other than @code{master} are considered
-@emph{frozen} if there has been a recent evaluation, or there is a
-corresponding @code{-next} branch. Please ask on the mailing list or
-IRC if unsure where to place a patch.
+When we decide to start building the @code{staging} or
+@code{core-updates} branches, they will be forked and renamed with the
+suffix @code{-frozen}, at which time only bug fixes may be pushed to the
+frozen branches. The @code{core-updates} and @code{staging} branches
+will remain open to accept patches for the next cycle. Please ask on
+the mailing list or IRC if unsure where to place a patch.
@c TODO: It would be good with badges on the website that tracks these
@c branches. Or maybe even a status page.
has already been pushed to the Savannah-hosted Guix git repository.
This check can be disabled, @emph{at your own peril}, by setting the
-@code{GUIX_ALLOW_ME_TO_USE_PRIVATE_COMMIT} environment variable.
-
-To build the resulting 'guix' package when using a private commit, the
-following command can be used:
-
-@example
-./pre-inst-env guix build guix --with-git-url=guix=$PWD
-@end example
+@code{GUIX_ALLOW_ME_TO_USE_PRIVATE_COMMIT} environment variable. When
+this variable is set, the updated package source is also added to the
+store. This is used as part of the release process of Guix.
HCoop / jackhill / guix / guix.git / blobdiff