diff --git a/doc/guix.texi b/doc/guix.texi index 4d974be53e..ef3b8e127e 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -19019,20 +19019,33 @@ words, it is possible to define services that provide additional mcron jobs to run. @end defvr +@c Generated via (generate-documentation) at the bottom of (gnu services +@c mcron). +@c %start of fragment @deftp {Data Type} mcron-configuration -Data type representing the configuration of mcron. +Available @code{mcron-configuration} fields are: @table @asis -@item @code{mcron} (default: @var{mcron}) +@item @code{mcron} (default: @code{mcron}) (type: file-like) The mcron package to use. -@item @code{jobs} +@item @code{jobs} (default: @code{()}) (type: list-of-gexps) This is a list of gexps (@pxref{G-Expressions}), where each gexp corresponds to an mcron job specification (@pxref{Syntax, mcron job -specifications,, mcron, GNU@tie{}mcron}). +specifications,, mcron,GNU@tie{}mcron}). + +@item @code{log?} (default: @code{#t}) (type: boolean) +Log messages to standard output. + +@item @code{log-format} (default: @code{"~1@@*~a ~a: ~a~%"}) (type: string) +@code{(ice-9 format)} format string for log messages. The default value +produces messages like "@samp{@var{pid} @var{name}: @var{message}"} +(@pxref{Invoking mcron, Invoking,, mcron,GNU@tie{}mcron}). Each message +is also prefixed by a timestamp by GNU Shepherd. + @end table @end deftp - +@c %end of fragment @node Log Rotation @subsection Log Rotation @@ -41068,18 +41081,32 @@ jobs to run. @end defvr @deftp {Data Type} home-mcron-configuration -Data type representing the configuration of mcron. +Available @code{home-mcron-configuration} fields are: +@c Auto-generated with (gnu home services mcron)'s +@c generate-documentation procedure. +@c %start of fragment @table @asis -@item @code{mcron} (default: @var{mcron}) +@item @code{mcron} (default: @code{mcron}) (type: file-like) The mcron package to use. -@item @code{jobs} +@item @code{jobs} (default: @code{()}) (type: list-of-gexps) This is a list of gexps (@pxref{G-Expressions}), where each gexp corresponds to an mcron job specification (@pxref{Syntax, mcron job -specifications,, mcron, GNU@tie{}mcron}). +specifications,, mcron,GNU@tie{}mcron}). + +@item @code{log?} (default: @code{#t}) (type: boolean) +Log messages to standard output. + +@item @code{log-format} (default: @code{"~1@@*~a ~a: ~a~%"}) (type: string) +@code{(ice-9 format)} format string for log messages. The default value +produces messages like "@samp{@var{pid} @var{name}: @var{message}"} +(@pxref{Invoking mcron, Invoking,, mcron,GNU@tie{}mcron}). Each message +is also prefixed by a timestamp by GNU Shepherd. + @end table @end deftp +@c %end of fragment @node Power Management Home Services @subsection Power Management Home Services diff --git a/gnu/home/services/mcron.scm b/gnu/home/services/mcron.scm index 0b3dbb810b..1d294a997c 100644 --- a/gnu/home/services/mcron.scm +++ b/gnu/home/services/mcron.scm @@ -1,6 +1,7 @@ ;;; GNU Guix --- Functional package management for GNU ;;; Copyright © 2021 Andrew Tropin ;;; Copyright © 2021 Xinglu Chen +;;; Copyright © 2022 Maxim Cournoyer ;;; ;;; This file is part of GNU Guix. ;;; @@ -20,6 +21,7 @@ (define-module (gnu home services mcron) #:use-module (gnu packages guile-xyz) #:use-module (gnu home services) + #:use-module (gnu services configuration) #:use-module (gnu services shepherd) #:use-module (gnu home services shepherd) #:use-module (guix records) @@ -53,13 +55,23 @@ ;; ;;; Code: -(define-record-type* home-mcron-configuration - make-home-mcron-configuration - home-mcron-configuration? - (package home-mcron-configuration-package ; package - (default mcron)) - (jobs home-mcron-configuration-jobs ; list of jobs - (default '()))) +(define list-of-gexps? + (list-of gexp?)) + +(define-configuration/no-serialization home-mcron-configuration + (mcron (file-like mcron) "The mcron package to use.") + (jobs + (list-of-gexps '()) + "This is a list of gexps (@pxref{G-Expressions}), where each gexp +corresponds to an mcron job specification (@pxref{Syntax, mcron job +specifications,, mcron, GNU@tie{}mcron}).") + (log? (boolean #t) "Log messages to standard output.") + (log-format + (string "~1@*~a ~a: ~a~%") + "@code{(ice-9 format)} format string for log messages. The default value +produces messages like \"@samp{@var{pid} @var{name}: +@var{message}\"} (@pxref{Invoking mcron, Invoking,, mcron, GNU@tie{}mcron}). +Each message is also prefixed by a timestamp by GNU Shepherd.")) (define job-files (@@ (gnu services mcron) job-files)) (define shepherd-schedule-action @@ -69,19 +81,23 @@ (match-lambda (($ mcron '()) ; no jobs to run '()) - (($ mcron jobs) + (($ mcron jobs log? log-format) (let ((files (job-files mcron jobs))) (list (shepherd-service (documentation "User cron jobs.") (provision '(mcron)) (modules `((srfi srfi-1) (srfi srfi-26) - (ice-9 popen) ; for the 'schedule' action + (ice-9 popen) ; for the 'schedule' action (ice-9 rdelim) (ice-9 match) ,@%default-modules)) (start #~(make-forkexec-constructor - (list #$(file-append mcron "/bin/mcron") #$@files) + (list (string-append #$mcron "/bin/mcron") + #$@(if log? + #~("--log" "--log-format" #$log-format) + #~()) + #$@files) #:log-file (string-append (or (getenv "XDG_LOG_HOME") (format #f "~a/.local/var/log" @@ -91,7 +107,7 @@ (actions (list (shepherd-schedule-action mcron files))))))))) -(define home-mcron-profile (compose list home-mcron-configuration-package)) +(define home-mcron-profile (compose list home-mcron-configuration-mcron)) (define (home-mcron-extend config jobs) (home-mcron-configuration @@ -113,3 +129,12 @@ (default-value (home-mcron-configuration)) (description "Install and configure the GNU mcron cron job manager."))) + + +;;; +;;; Generate documentation. +;;; +(define (generate-doc) + (configuration->documentation 'home-mcron-configuration)) + +;;; mcron.scm ends here diff --git a/gnu/services/mcron.scm b/gnu/services/mcron.scm index 23760ebda4..52332d6123 100644 --- a/gnu/services/mcron.scm +++ b/gnu/services/mcron.scm @@ -1,5 +1,6 @@ ;;; GNU Guix --- Functional package management for GNU ;;; Copyright © 2016, 2017, 2018, 2019, 2020 Ludovic Courtès +;;; Copyright © 2022 Maxim Cournoyer ;;; ;;; This file is part of GNU Guix. ;;; @@ -18,6 +19,7 @@ (define-module (gnu services mcron) #:use-module (gnu services) + #:use-module (gnu services configuration) #:use-module (gnu services shepherd) #:use-module (gnu packages guile-xyz) #:use-module (guix deprecation) @@ -30,6 +32,8 @@ mcron-configuration? mcron-configuration-mcron mcron-configuration-jobs + mcron-configuration-log? + mcron-configuration-log-format mcron-service-type)) @@ -48,13 +52,23 @@ ;;; ;;; Code: -(define-record-type* mcron-configuration - make-mcron-configuration - mcron-configuration? - (mcron mcron-configuration-mcron ;file-like - (default mcron)) - (jobs mcron-configuration-jobs ;list of - (default '()))) +(define list-of-gexps? + (list-of gexp?)) + +(define-configuration/no-serialization mcron-configuration + (mcron (file-like mcron) "The mcron package to use.") + (jobs + (list-of-gexps '()) + "This is a list of gexps (@pxref{G-Expressions}), where each gexp +corresponds to an mcron job specification (@pxref{Syntax, mcron job +specifications,, mcron, GNU@tie{}mcron}).") + (log? (boolean #t) "Log messages to standard output.") + (log-format + (string "~1@*~a ~a: ~a~%") + "@code{(ice-9 format)} format string for log messages. The default value +produces messages like \"@samp{@var{pid} @var{name}: +@var{message}\"} (@pxref{Invoking mcron, Invoking,, mcron, GNU@tie{}mcron}). +Each message is also prefixed by a timestamp by GNU Shepherd.")) (define (job-files mcron jobs) "Return a list of file-like object for JOBS, a list of gexps." @@ -124,21 +138,25 @@ files." (define mcron-shepherd-services (match-lambda - (($ mcron ()) ;nothing to do! + (($ mcron ()) ;nothing to do! '()) - (($ mcron jobs) + (($ mcron jobs log? log-format) (let ((files (job-files mcron jobs))) (list (shepherd-service (provision '(mcron)) (requirement '(user-processes)) (modules `((srfi srfi-1) (srfi srfi-26) - (ice-9 popen) ;for the 'schedule' action + (ice-9 popen) ;for the 'schedule' action (ice-9 rdelim) (ice-9 match) ,@%default-modules)) (start #~(make-forkexec-constructor - (list (string-append #$mcron "/bin/mcron") #$@files) + (list (string-append #$mcron "/bin/mcron") + #$@(if log? + #~("--log" "--log-format" #$log-format) + #~()) + #$@files) ;; Disable auto-compilation of the job files and set a ;; sane value for 'PATH'. @@ -172,4 +190,11 @@ files." jobs))))) (default-value (mcron-configuration)))) ;empty job list + +;;; +;;; Generate documentation. +;;; +(define (generate-doc) + (configuration->documentation 'mcron-configuration)) + ;;; mcron.scm ends here