diff options
author | Liliana Marie Prikler <liliana.prikler@gmail.com> | 2022-08-06 08:55:03 +0200 |
---|---|---|
committer | Guix Patches Tester <> | 2022-11-18 12:54:26 +0100 |
commit | 4e39faf765dc152a08fe0c7f0f505a34a93bc614 (patch) | |
tree | 759cc325afc03327838c98c29f53f58793a34c5f | |
parent | 983906ab72307a5b848a54233b30d9744356de07 (diff) | |
download | guix-patches-4e39faf765dc152a08fe0c7f0f505a34a93bc614.tar guix-patches-4e39faf765dc152a08fe0c7f0f505a34a93bc614.tar.gz |
doc: Update contribution guidelines on patches, etc.issue-57598
* doc/contributing.texi ("Snippets versus Phases"): Replaced with...
("Modifying Sources"): ... this. List more use cases and some principles.
-rw-r--r-- | doc/contributing.texi | 115 |
1 files changed, 102 insertions, 13 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 40ae33ecac..cb395117ce 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -451,7 +451,7 @@ needed is to review and apply the patch. * Package Naming:: What's in a name? * 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. +* Modifying Sources:: When to use patches, snippets, or build phases. * Emacs Packages:: Your Elisp fix. * Python Modules:: A touch of British comedy. * Perl Modules:: Little pearls. @@ -708,20 +708,109 @@ Gettext}): for the X11 resize-and-rotate (RandR) extension. @dots{}") @end lisp -@node Snippets versus Phases -@subsection Snippets versus Phases +@node Modifying Sources +@subsection Modifying Sources +@cindex patches, when to use @cindex snippets, when to use -The boundary between using an origin snippet versus a build phase to -modify the sources of a package can be elusive. Origin snippets are -typically used to remove unwanted files such as bundled libraries, -nonfree sources, or to apply simple substitutions. The source derived -from an origin should produce a source that can be used to build the -package on any system that the upstream package supports (i.e., act as -the corresponding source). In particular, origin snippets must not -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}). + +Guix has three main ways of modifying the source code of a package, +that you as a packager may use. Each one has its strengths and +drawbacks, along with intended and historically derived use cases. +These are + +@table @b + +@item patches +If your package has a bug that takes multiple lines to fix, or a fix +has already been accepted upstream, patches are the preferred way of +eliminating said bug.@footnote{If you patch a bug that has hitherto +not been reported or fixed upstream, consider also contacting upstream +unless the bug and its fix are specific to Guix.} +Refer to the @code{origin} record documentation +(particularly the fields @code{patches}, @code{patch-inputs}, and +@code{patch-flags}) for more information on how to use patches +(@pxref{origin Reference}). +When adding a patch, do not forget to also list it in +@code{dist_patch_DATA} of @file{gnu/local.mk} + +As patches are applied to the origin of a package, they become part +of the corresponding source. You can retrieve this source by +invoking @code{guix build -S YOUR_PACKAGE}. This also means that +modifying the patch causes two rebuilds: one for the source and one +for the package built from it. + +Patches are limited in that they lack the expressiveness of Guile. +If all changes are constrained to single lines, a patch might be much +larger than the equivalent @code{substitute*}. It is further bad form +to use a single patch to address multiple unrelated issues, whereas +snippets can take ``multiple jobs''. + +@item snippets +If your package contains non-free sources, these need to be removed +through a snippet. This snippet should not only remove the sources in +question, but also references to the removed sources in build scripts, +documentation, and so on. @ref{Software Freedom} + +If your package bundles external libraries, snippets are the preferred +way of removing said them. Unlike with non-free sources, it is not a +requirement to remove @emph{all} bundled libraries, although doing so +is very much preferred. Bundled libraries that are kept should be +clearly indicated, preferrably with a reason as to why the bundled copy +remains. As with non-free sources, references to the removed libraries +should also be updated in the snippet. + +Refer to the @code{origin} record documentation +(particularly the fields @code{snippet} and @code{modules}), for more +information on how to use snippets (@pxref{origin Reference}). + +While snippets have all of Guile's core as well as extra @code{modules} +available, their most useful procedure for @emph{editing} sources +(rather than removing them), is @code{substitute*}, which can not deal +with multi-line changes that well. Like patches, snippets become part +of the corresponding source. + +@item build phases +For modifications that retain the intended functionality of the +package, build phases (usually between @code{unpack} and +@code{configure}, sometimes between @code{configure} and @code{build}) +can be used. @ref{Build Phases}. +Such changes include, but are not limited to, fixes of the +build script(s) or embeddings of store paths (e.g. replacement of +@file{/bin/sh} with @code{(search-input-file inputs "bin/sh")}). + +If you need to embed a store path, do so only inside a build phase. +A workaround for patches that span multiple lines, is to use a variable +such as @code{@@store_path@@} inside the patch and substitute the actual +store path at build time via @code{substitute*}. + +Unlike patches and snippets, build phases do @b{not} become part of +the corresponding source of a package, and should thus be avoided for +changes that result in observably different runtime behaviour. +On the other hand, the reduced overhead of unpacking, repacking and +unpacking again might make for a slightly more pleasant debugging +experience. + +@end table + +If your change does not neatly fit in any of the categories above, it +is usually a matter of preference or convenience. + +@cindex auxiliary files + +Sometimes, you may need to add a new file, e.g. a source file or +configuration file, to your package. As a matter of principle +@b{auxiliary files} should be preferred over an equivalent +@code{display} or @code{format} when creating non-trivial files, as that +makes them easier to edit. The exact threshold for a non-trivial file +might be subjective, though it should lie somewhere between +10--20 lines. + +Auxiliary files are stored in the @file{gnu/packages/aux-files} +directory and can be retrieved in a snippet or build phase via +@code{search-auxiliary-file}. +When adding an auxiliary file, do not forget to also list it in +@code{AUX_FILES} of @file{Makefile.am}. @node Emacs Packages @subsection Emacs Packages |