Parameterized Packages: The Second Update

To make global parameters useful, it is necessary to be able to change the contents of a package in ways that Package Transformations might not be able to by themselves. Additionally, users might find themselves in situations where they wish to perform different operations for different values of an enumerated type.

"Parametric Variants" refers to matching against enumerated values and using methods of Defining Package Variants, such as package transforms, modify-inputs and procedures that return packages. Parameters now can use any of these methods instead of just using transformations.

For a better understanding of them, please look at any of the examples using the variant-match macro.

It's possible that enabling a parameter might require enabling another parameter or a package. For such situations, I've added a new dependencies field to the parameter record that lets users specify parameters or packages a given parameter depends on. You can also fine-tune values for the parameter and the parameters in dependencies.

The usage format for parameters is the same as that for other package transforms- you specify them through the CLI. In the future, it will also be possible to have a global set of transforms.

guix install emacs-parameterized \
     --with-parameter=emacs-parameterized=pgtk=on \
     --with-parameter=emacs-parameterized=tree-sitter=on \

EDIT 9/18/2023: as the package record's source field is not thunked, I'm instead using a #:lambda inside the next package parameter to change it.

Under the hood, this is what the implementation looks like.

(package-with-parameters
 [parameter-spec
  (local
    (list
     (package-parameter 
      (name 'next)
      (variants
       (parameter-variant-match
        (_
         #:lambda
         (lambda (pkg)
           (package
            (inherit pkg)
            (version "29.0.92")
            (source
             (origin
              (inherit (package-source pkg))
              (method git-fetch)
              (uri
               (git-reference
                (url "https://git.savannah.gnu.org/git/emacs.git/")
                (commit (string-append "emacs-" version))))
              (file-name
               (git-file-name (package-name pkg) version))
              (patches
               (parameter-if #:package pkg (pgtk)
                             (search-patches
                              "emacs-exec-path.patch"
                              "emacs-fix-scheme-indent-function.patch"
                              "emacs-native-comp-driver-options.patch"
                              "emacs-pgtk-super-key-fix.patch")
                             (search-patches
                              "emacs-exec-path.patch"
                              "emacs-fix-scheme-indent-function.patch"
                              "emacs-native-comp-driver-options.patch")))
              (sha256
               (base32
         "1h3p325859svcy43iv7wr27dp68049j9d44jq5akcynqdkxz4jjn"))))))))))
     (package-parameter (name 'tree-sitter)
                        (dependencies '(next)))
     (package-parameter
      (name 'pgtk)
      (variants
       (parameter-variant-match
        (_ #:transform (with-configure-flag
                        #:package-name "=--with-pgtk"))))
      (dependencies '(tree-sitter x11)))
     (package-parameter
      (name 'xwidgets)
      (variants
       (parameter-variant-match
        (_ #:transform (with-configure-flag
                        #:package-name "=--with-xwidgets")))))
     (package-parameter
      (name 'wide-int)
      (variants
       (parameter-variant-match
        (_ #:transform (with-configure-flag
                        #:package-name "=--with-wide-int")))))))
  (one-of '((_ (x11 #:off) pgtk)
            (_ (x11 #:off) xwidgets)))]
 (inherit emacs)
 (name "emacs-parameterized")
 (arguments
  (parameter-substitute-keyword-arguments 
   (package-arguments emacs)
   [((x11 #:off))
    '(((#:configure-flags flags #~'())
       #~(delete "--with-cairo" #$flags))
      ((#:modules _) (%emacs-modules build-system))
      ((#:phases phases)
       #~(modify-phases #$phases
                        (delete 'restore-emacs-pdmp)
                        (delete 'strip-double-wrap))))]
   [(#:all (xwidgets on) (pgtk #:off))
    '(((#:configure-flags flags #~'())
       #~(cons "--with-xwidgets" #$flags))
      ((#:modules _) (%emacs-modules build-system))
      ((#:phases phases)
       #~(modify-phases #$phases
                        (delete 'restore-emacs-pdmp)
                        (delete 'strip-double-wrap))))]))
 (inputs
  (parameter-modify-inputs
   [(next) (prepend sqlite)]
   [(tree-sitter) (prepend tree-sitter)]
   [(xwidgets) (prepend gsettings-desktop-schemas
                        webkitgtk-with-libsoup2)]
   [((x11 #:off))
    (delete "libx11" "gtk+" "libxft" "libtiff" "giflib" "libjpeg"
            "imagemagick" "libpng" "librsvg" "libxpm" "libice" "libsm"
            "cairo" "pango" "harfbuzz" "libotf" "m17n-lib" "dbus")])))

1. package-with-parameters: This macro takes a parameter-spec as its first argument and applies the parameter specification to the package in its body. The default parameters are then activated within the package.
2. parameter-spec: This record type contains all of the logic necessary to declare and resolve parameters for a package. This normally goes inside the properties field of the package record. In the previous post, it was necessary to put this record inside the properties, but now package-with-parameters handles that for us. The parameter specification record contains various fields, all of which are optional. I have gone over the fields in detail in the previous blog post, hence I will not explain all of them in detail here. The only big change is that one-of now has a functionality wherein if you start a list within it with _, you can have a case where none of the values in it are positive. Otherwise, it throws an error as one and only one value is expected to be positive. Also notice the usage of #:off to indicate negation. We have also not declared x11, which will hence be treated as a global parameter. In general global parameters must either have their predicate set to something that returns #t or be present anywhere in the parameter-spec to be applicable. Users are advised to put them in the optional field, as it was created with this use case in mind.
3. local parameter next: The local parameter next has an interesting #:lambda statement inside it. This statement takes the current package record as an argument and returns a new package record, which is then used in its place. This is an extremely powerful method for changing otherwise unchangeable options, such as the ones here; because the version and source fields are not thunked, this is the only way of modifying them. The #:lambda's functions can be passed 0, 1 or 2 arguments. In the case that it asks for 1 argument, the current package record is passed. If it asks for 2, the current package record along with the given parameter's value are passed. In all cases, the function is expected to return a package record that will then be taken as the new current package record.
4. package body: Within the package body, we have the usual fields you would expect. (inherit emacs) signifies that this package inherits all of emacs' base fields, and the rest of the fields are overrides of that. Please note that the name field cannot be influenced by parameters as it is not thunked.
5. parameter-match: note: this has been substituted by parameter-substitute-keyword-arguments in the latest edit This is an extremely useful macro that matches all the parameter lists that has any positive parameters. It is also possible to require all the parameters in a list to be positive by using #:all. Please keep in mind that it does not short-circuit by default like cond. It will keep matching parameters until all the lists have been combed through. A short-circuiting version exists in the form of parameter-match-case. I've gone over the functionality offered by this macro in detail in the previous blog post, however it has one small improvement: all conditionals now support checking if a parameter is set to a particular value instead of just checking if it is positive or not. This is very useful for enumerated types, where you might for example want to disable some features if and only if a parameter is set to the second positive value. To illustrate this, if you wanted to check whether a parameter y is set to v1 or if the parameter list z is non-negative, the list would be ((y v1) z). You can also use this to check for the default or negative value, with (parameter-name #:default) and (parameter-name #:off) respectively. _ is a similar special symbol which matches all non-negative values, but it is not necessary to use it since the parameter name by itself, say parameter-name is the same as (parameter-name _). We can see this in the ((y v1) z) example above, where z is matching all non-negative values of z even though we did not specify it as (z _). You can also use this in all of the fields in parameter-spec that require you to specify parameters. The parameter value list syntax is the same everywhere.
6. parameter-substitute-keyword-arguments and parameter-modify-inputs: As explained in the previous blog post, because modify-inputs is a macro, we cannot use parameter-match within it. To counter this, I have written parameter-modify-inputs that behaves a lot like if modify-inputs had a parameter-match macro within it. I have similarly written parameter-substitute-keyword-arguments for another commonly used macro called substitute-keyword-arguments.

I have gone over the rest of the conditionals in the previous blog post too, they remain more or less the same with the exception that we use #:all inside lists instead of all like last time. This is to make it obvious at a glance that #:all is not a parameter like the rest of the list.

gcc has a set of optimization flags that can be used to make programs faster or smaller at the expense of stability. This is a very basic attempt at adding that functionality to the gnu-build-system through the CFLAGS make-flag.

(package-parameter
 (name 'gcc-oflag)
 (type
  (parameter-type
   (name '_)
   (accepted-values '(-O0 -O1 -O2 -O3 -Os -Ofast -Og -Oz))
   (negation #f)))
 (variants
  (parameter-variant-match
   (_ #:build-system gnu-build-system
      #:lambda
      (lambda (pkg parameter-value)
        (package
         (inherit pkg)
         (arguments
          (substitute-keyword-arguments
           (package-arguments package)
           ((#:make-flags flags #~'())
            #~(append
               #$flags
               (list (string-append "CFLAGS="
                                    parameter-value))))))))))))

In High-Performance Computing, it's often necessary to produce static builds of packages to share them with others. This parameter is a basic attempt at making it possible to do so with any given library.

(package-parameter
 (name 'static-lib)
 (variants
  (parameter-variant-match
   (_ #:transform
      (with-configure-flag #:package-name "=--disable-shared")
      (with-configure-flag #:package-name "=--enable-static")))))

I recently made a post on Mastodon that claimed that the real advantage of Guix is that it's extensible with Guile Scheme. To back up this claim, once parameters have been merged to trunk I'll be writing a set of tutorials on hacking Guix with Guile Scheme. One of these planned tutorials is going to be about writing a RESTful API using Guile that'll allow users to request a package with specific parameters. Here is what the POST request for this API may look like:

POST /test HTTP/1.1
Host: guix.example
Accept: application/json
Content-Type: application/json
Content-Length: 194

{
  "User" : "guix-hacker",
  "Package" : "emacs",
  "Parameters" : [
      { "Parameter" : "next",
        "Value" : "on"},
      { "Parameter" : "tree-sitter",
        "Value" : "off"}
      ]
}