summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2016-09-01 22:35:35 +0200
committerLudovic Courtès <ludo@gnu.org>2016-09-01 23:07:54 +0200
commit2a75b0b63dbf123023c1c7ae99cf01a3866612a1 (patch)
tree3bcda01194b81471be5df1eb0e698b9c29986095 /doc
parent705b97147735dd8cb1d3bf74e0f1a91b50cc7f41 (diff)
packages: Add 'package-input-rewriting'.
* guix/packages.scm (package-input-rewriting): New procedure. * tests/packages.scm ("package-input-rewriting"): New test. * doc/guix.texi (Defining Packages): Document it. (Package Transformation Options): Add cross-reference.
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi42
1 files changed, 41 insertions, 1 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index 5448c66664..2a7fd4d041 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2574,6 +2574,45 @@ and operating system, such as @code{"mips64el-linux-gnu"}
Configure and Build System}).
@end deffn
+@cindex package transformations
+@cindex input rewriting
+@cindex dependency tree rewriting
+Packages can be manipulated in arbitrary ways. An example of a useful
+transformation is @dfn{input rewriting}, whereby the dependency tree of
+a package is rewritten by replacing specific inputs by others:
+
+@deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
+ [@var{rewrite-name}]
+Return a procedure that, when passed a package, replaces its direct and
+indirect dependencies (but not its implicit inputs) according to
+@var{replacements}. @var{replacements} is a list of package pairs; the
+first element of each pair is the package to replace, and the second one
+is the replacement.
+
+Optionally, @var{rewrite-name} is a one-argument procedure that takes
+the name of a package and returns its new name after rewrite.
+@end deffn
+
+@noindent
+Consider this example:
+
+@example
+(define libressl-instead-of-openssl
+ ;; This is a procedure to replace OPENSSL by LIBRESSL,
+ ;; recursively.
+ (package-input-rewriting `((,openssl . ,libressl))))
+
+(define git-with-libressl
+ (libressl-instead-of-openssl git))
+@end example
+
+@noindent
+Here we first define a rewriting procedure that replaces @var{openssl}
+with @var{libressl}. Then we use it to define a @dfn{variant} of the
+@var{git} package that uses @var{libressl} instead of @var{openssl}.
+This is exactly what the @option{--with-input} command-line option does
+(@pxref{Package Transformation Options, @option{--with-input}}).
+
@menu
* package Reference :: The package data type.
* origin Reference:: The origin data type.
@@ -4362,7 +4401,8 @@ This is a recursive, deep replacement. So in this example, both
@code{guix} and its dependency @code{guile-json} (which also depends on
@code{guile}) get rebuilt against @code{guile-next}.
-However, implicit inputs are left unchanged.
+This is implemented using the @code{package-input-rewriting} Scheme
+procedure (@pxref{Defining Packages, @code{package-input-rewriting}}).
@end table
@node Additional Build Options