guix-parameters/NOTES/BLOG/parameterized-packages.org

What are Parameterized Packages?

I will be working on bringing Parameterized Packages to GNU Guix this summer as a part of the Google Summer of Code program under the mentorship of Pjotr Prins and Gábor Boskovits. This post will go over the basic ideas behind Parameterized Packages, their benefits and how I am planning on implementing them. Parameterized packages will provide users with a simple way to configure many aspects of packages, à la Gentoo USE flags.

GNU Guix is the only GNU/Linux distribution capable of achieving a full-source bootstrap, and this comes with many unique advantages. Every package in Guix can be built from source, and as a result it is possible to configure a wide variety of options for each package that just aren't exposed on binary-based distributions using Package Transformations. While package transformations are extremely powerful, they require some experience with packaging software for Guix and are generally expected to be used by power users for applications such as High-Performance Computing.

Parameterized Packages aim to not only bring the benefits of package transformations to all users, but to also make it possible to globally specify some aspects to include or exclude from packages similar to Gentoo's USE flags.

Example Usage

Some of the benefits of Parameterized Packages are:
1. Significantly smaller binaries
2. More fine-grained control over the entire system
3. Access to additional features only accessible through compile-time options
Among many more. Here is an example config.scm file with parameters:

(use-modules (gnu parameters)

 (operating-system
   ;; ...
   (parameters '(x11 wayland! alsa)))

In this example, the user wants to build all the packages in the system with support for X11 and alsa, and without Wayland support. Note that all parameter names are lowercase, and that ~!~ indicates the negation of a parameter.

Another possible way of using parameters is through the command-line interface, for example

  guix build emacs --with-parameter=emacs="png!"

Example Usage for Package Maintainers

This will build Emacs without PNG support. The user interface is very much subject to change, and I would love input from Guix users on the same. Package definitions with parameters will look like this:

 (define-public emacs
   (package
     (parameters (and
       (optional jit^ png^ alsa^)
       (one-of motif gtk^ x11!*)))
     (parameter-transforms
       ((x11!)
        (changes-to-be-made-to-the-package)))))

The ^ indicates that inclusion of a certain parameter is default. This is very important as if parameters are not specified or if a package is a dependency of another package without parameters, the default version is used. ~(optional ...)~ is syntactic sugar for (p-or ... #t) and (one-of ...) translates to (p-xor ...). Note that while p-or behaves like the regular or logic gate, it does not short circuit. The (and ...) within (parameters ...) must resolve to #t, otherwise the default version of the package will be used. When a * is added to a parameter, it means that a generic transform cannot be used- every build system has standard transforms for parameters, and if your package requires a non-standard transform when the given parameters is used this is what you use to specify that. In the (package-transforms ...) macro each of these non-standard transforms is specified. Package-transforms can also contain specific cases like (and x11! alsa) if the transforms for both do not compose.

Alternatively, the following arguably simpler syntax may be employed: