me
/
guix
Archived
1
0
Fork 0
Code

doc: cuirass: Update documentation. 

* doc/guix.texi (Continuous Integration): Update Cuirass documentation.
master
Mathieu Othacehe 2021-03-23 20:30:17 +01:00
parent feb68a26cc
commit 90d166e510
No known key found for this signature in database
GPG Key ID: 8354763531769CA6
1 changed files with 141 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

196
doc/guix.texi
View File

@ -27085,9 +27085,9 @@ The verbosity level of the daemon.
@subsection Continuous Integration
@cindex continuous integration
@uref{https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git, Cuirass} is a
continuous integration tool for Guix. It can be used both for development and
for providing substitutes to others (@pxref{Substitutes}).
@uref{https://guix.gnu.org/cuirass/, Cuirass} is a continuous
integration tool for Guix. It can be used both for development and for
providing substitutes to others (@pxref{Substitutes}).
The @code{(gnu services cuirass)} module provides the following service.
@ -27096,45 +27096,44 @@ The type of the Cuirass service. Its value must be a
@code{cuirass-configuration} object, as described below.
@end defvr
To add build jobs, you have to set the @code{specifications} field of the
configuration. Here is an example of a service that polls the Guix repository
and builds the packages from a manifest. Some of the packages are defined in
the @code{"custom-packages"} input, which is the equivalent of
@env{GUIX_PACKAGE_PATH}.
To add build jobs, you have to set the @code{specifications} field of
the configuration. For instance, the following example will build all
the packages provided by the @code{my-channel} channel.
@lisp
(define %cuirass-specs
#~(list
'((#:name . "my-manifest")
(#:load-path-inputs . ("guix"))
(#:package-path-inputs . ("custom-packages"))
(#:proc-input . "guix")
(#:proc-file . "build-aux/cuirass/gnu-system.scm")
(#:proc . cuirass-jobs)
(#:proc-args . ((subset . "manifests")
(systems . ("x86_64-linux"))
(manifests . (("config" . "guix/manifest.scm")))))
(#:inputs . (((#:name . "guix")
(#:url . "git://git.savannah.gnu.org/guix.git")
(#:load-path . ".")
(#:branch . "master")
(#:no-compile? . #t))
((#:name . "config")
(#:url . "https://git.example.org/config.git")
(#:load-path . ".")
(#:branch . "master")
(#:no-compile? . #t))
((#:name . "custom-packages")
(#:url . "https://git.example.org/custom-packages.git")
(#:load-path . ".")
(#:branch . "master")
(#:no-compile? . #t)))))))
#~(list (specification
(name "my-channel")
(build '(channels my-channel))
(channels
(cons (channel
(name 'my-channel)
(url "https://my-channel.git"))
%default-channels)))))
(service cuirass-service-type
(cuirass-configuration
(specifications %cuirass-specs)))
@end lisp
To build the @code{linux-libre} package defined by the default Guix
channel, one can use the following configuration.
@lisp
(define %cuirass-specs
#~(list (specification
(name "my-linux")
(build '(packages "linux-libre")))))
(service cuirass-service-type
(cuirass-configuration
(specifications %cuirass-specs)))
@end lisp
The other configuration possibilities, as well as the specification
record itself are described in the Cuirass manual
(@pxref{Specifications,,, cuirass, Cuirass}).
While information related to build jobs is located directly in the
specifications, global settings for the @command{cuirass} process are
accessible in other @code{cuirass-configuration} fields.
@ -27143,20 +27142,15 @@ accessible in other @code{cuirass-configuration} fields.
Data type representing the configuration of Cuirass.
@table @asis
@item @code{cuirass} (default: @code{cuirass})
The Cuirass package to use.
@item @code{log-file} (default: @code{"/var/log/cuirass.log"})
Location of the log file.
@item @code{web-log-file} (default: @code{"/var/log/cuirass-web.log"})
Location of the log file used by the web interface.
@item @code{queries-log-file} (default: @code{#f})
Location of the SQL queries log file. By default, SQL queries logging is
disabled.
@item @code{web-queries-log-file} (default: @code{#f})
Location of the web SQL queries log file. By default, web SQL queries
logging is disabled.
@item @code{cache-directory} (default: @code{"/var/cache/cuirass"})
Location of the repository cache.
@ -27170,17 +27164,19 @@ Owner's group of the @code{cuirass} process.
Number of seconds between the poll of the repositories followed by the
Cuirass jobs.
@item @code{queue-size} (default: @code{1})
Size of the database writer queue.
@item @code{parameters} (default: @code{#f})
Read parameters from the given @var{parameters} file. The supported
parameters are described here (@pxref{Parameters,,, cuirass, Cuirass}).
@item @code{database} (default: @code{"/var/lib/cuirass/cuirass.db"})
Location of sqlite database which contains the build results and previously
added specifications.
@item @code{remote-server} (default: @code{#f})
A @code{cuirass-remote-server-configuration} record to use the build
remote mechanism or @code{#f} to use the default build mechanism.
@item @code{ttl} (default: @code{(* 30 24 3600)})
Specifies the time-to-live (TTL) in seconds of garbage collector roots that
are registered for build results. This means that build results are protected
from garbage collection for at least @var{ttl} seconds.
@item @code{database} (default: @code{"dbname=cuirass host=/var/run/postgresql"})
Use @var{database} as the database containing the jobs and the past
build results. Since Cuirass uses PostgreSQL as a database engine,
@var{database} must be a string such as @code{"dbname=cuirass
host=localhost"}.
@item @code{port} (default: @code{8081})
Port number used by the HTTP server.
@ -27190,11 +27186,9 @@ Listen on the network interface for @var{host}. The default is to
accept connections from localhost.
@item @code{specifications} (default: @code{#~'()})
A gexp (@pxref{G-Expressions}) that evaluates to a list of specifications,
where a specification is an association list
(@pxref{Associations Lists,,, guile, GNU Guile Reference Manual}) whose
keys are keywords (@code{#:keyword-example}) as shown in the example
above.
A gexp (@pxref{G-Expressions}) that evaluates to a list of
specifications records. The specification record is described in the
Cuirass manual (@pxref{Specifications,,, cuirass, Cuirass}).
@item @code{use-substitutes?} (default: @code{#f})
This allows using substitutes to avoid building every dependencies of a job
@ -27210,8 +27204,100 @@ packages locally.
@item @code{extra-options} (default: @code{'()})
Extra options to pass when running the Cuirass processes.
@end table
@end deftp
@cindex remote build
@subsubheading Cuirass remote building
Cuirass supports two mechanisms to build derivations.
@itemize
@item Using the local Guix daemon.
This is the default build mechanism. Once the build jobs are
evaluated, they are sent to the local Guix daemon. Cuirass then
listens to the Guix daemon output to detect the various build events.
@item Using the remote build mechanism.
The build jobs are not submitted to the local Guix daemon. Instead, a
remote server dispatches build requests to the connect remote workers,
according to the build priorities.
@end itemize
To enable this build mode a @code{cuirass-remote-server-configuration}
record must be passed as @code{remote-server} argument of the
@code{cuirass-configuration} record. The
@code{cuirass-remote-server-configuration} record is described below.
This build mode scales way better than the default build mode. This is
the build mode that is used on the GNU Guix build farm at
@url{https://ci.guix.gnu.org}. It should be preferred when using
Cuirass to build large amount of packages.
@deftp {Data Type} cuirass-remote-server-configuration
Data type representing the configuration of the Cuirass remote-server.
@table @asis
@item @code{backend-port} (default: @code{5555})
The TCP port for communicating with @code{remote-worker} processes
using ZMQ. It defaults to @code{5555}.
@item @code{log-port} (default: @code{5556})
The TCP port of the log server. It defaults to @code{5556}.
@item @code{publish-port} (default: @code{5557})
The TCP port of the publish server. It defaults to @code{5557}.
@item @code{log-file} (default: @code{"/var/log/cuirass-remote-server.log"})
Location of the log file.
@item @code{cache} (default: @code{"/var/cache/cuirass/remote"})
Use @var{cache} directory to cache build log files.
@item @code{trigger-url} (default: @code{#f})
Once a substitute is successfully fetched, trigger substitute baking at
@var{trigger-url}.
@item @code{public-key}
@item @code{private-key}
Use the specific @var{file}s as the public/private key pair used to sign
the store items being published.
@end table
@end deftp
At least one remote worker must also be started on any machine of the
local network to actually perform the builds and report their status.
@deftp {Data Type} cuirass-remote-worker-configuration
Data type representing the configuration of the Cuirass remote-worker.
@table @asis
@item @code{cuirass} (default: @code{cuirass})
The Cuirass package to use.
@item @code{workers} (default: @code{1})
Start @var{workers} parallel workers.
@item @code{server} (default: @code{#f})
Do not use Avahi discovery and connect to the given @code{server} IP
address instead.
@item @code{systems} (default: @code{(list (%current-system))})
Only request builds for the given @var{systems}.
@item @code{log-file} (default: @code{"/var/log/cuirass-remote-worker.log"})
Location of the log file.
@item @code{publish-port} (default: @code{5558})
The TCP port of the publish server. It defaults to @code{5558}.
@item @code{public-key}
@item @code{private-key}
Use the specific @var{file}s as the public/private key pair used to sign
the store items being published.
@end table
@end deftp