Re: Understanding Cuirass

[Mathieu Othacehe <m.othacehe@gmail.com>]

Hi Björn,

The Cuirass documentation should still be improved, so I understand your
questions. Here are some answers, feel free to improve the manual
afterwards :)

> * What should the procedure #:proc return?

The procedure #:proc takes exactly two arguments, the guix store and
an association list often called ARGUMENTS. The association list will
be the concatenation of #:proc-args and another association list
describing the sources that have been checked out by Cuirass, under
the form:

(INPUT-NAME (('file-name . "/gnu/store/path-of-the-checkouted-input")
             ('revision  . "git-sha1-of-the-checkouted-input")
             ('load-path . INPUT-LOAD-PATH)
	     ('no-compile? . INPUT-NO-COMPILE?)))

The role of #:proc is to return a list of 'jobs', which are mainly
derivations that have to be build.

They have to be under the following format:

(list (lambda ()
      	 ((#:job-name . "NAME-OF-THE-JOB")
   	  (#:derivation . "/gnu/store/derivation-to-build.drv")))
       ...)

> * What is the format of #:proc-args? Must this be an assoc-list or can
> it be just anything?

No I think it has to be an assoc-list otherwise, the procedure
FORMAT-CHECKOUTS of cuirass/bin/evaluate.in won't be happy.

Have a look to the HYDRA-JOBS procedure in
guix/build-aux/hydra/gnu-system.scm. It is wrapped by the CUIRASS-JOBS
procedure and passed as #:proc in
guix-maintenance/hydra/modules/sysadmin/services.scm (configuration of
Cuirass for the Berlin server).

HYDRA-JOBS will look for the following keys in ARGUMENTS:
* SUBSET ("core", "hello", (list of packages), (list of manifests)).
* SYSTEM ("x86_64-linux", "i686-linux", ...)

So, if we take the exemple of HYDRA-JOBS called with SUBSET to "hello"
and SYSTEM to "x86_64-linux", its role will be to return a list
containing exactly one job, giving the derivation of the "hello"
package for x86_64-linux, that has to be build.

> * How is that used? Is it always the second parameter to the proc?

See above.

> * And is the first one always a reference to the store?

Yes.

> In earlier examples like [0], the #:proc-file (then called #:file)
> could be a plain file lying around. Now it looks like it must be
> relative to one of its inputs, which is referenced by #:proc-input. Is
> this right? Is the old variant still possible?

Yes it is right. #:proc-file should be the path of the file containing
#:proc in the specified #:proc-input.

No, you cannot use #:file anymore.

>
> What forms can the inputs have? The documentation says it must always
> be git (either git:// or smart HTTPS). In examples/random.scm I saw
> also the form "file://", but when I tried it I got some error message
> (can't remember which one exactly). Is this allowed?

The #:url field of an input will be passed to the
LATEST-REPOSITORY-COMMIT of (guix git), using the CLONE procedure of
Guile-Git and the GIT-CLONE function of libgit2 in-fine.

I'm not sure what are the exact protocols supported by GIT-CLONE, you'll
have to inspect the libgit2 library. Maybe trying something like:

,use (guix git)
,use (guix store)
(latest-repository-commit (open-connection) "file://path-to-git-repo"
#:cache-directory "/tmp")

to see if it works!

Don't hesitate if you have other questions.

Mathieu