[bug#36875] [PATCH] doc: Document the use of `program-file' for mcron jobs.

[bug#36875] [PATCH] doc: Document the use of `program-file' for mcron jobs.

[Ricardo Wurmus]

Hi Maxim,

> This follows up to my second post under the thread at
> (https://lists.gnu.org/archive/html/help-guix/2019-07/msg00180.html).
>
> It aims to shed some light on (more) complex mcron job Guile scripting
> with the aid of Guix features (such as program-file).

I wonder if this can be worked around some other way, e.g. by adding
srfi-26 to the “with-imported-modules” clause.

I don’t fully understand the problem as described in the addition to the
manual.  What does “imported syntax definitions wouldn't work correctly”
mean?

It would be useful to state that this is something to do with srfi-26.

About the patch:

- please replace tabs with spaces.

- “Beep the system when the battery reaches %MIN-LEVEL or less battery
  percent.” sounds odd.  How about “Beep when the battery percentage
  falls below %MIN-LEVEL.”?

- Can the example be simplified further?  Is (setenv "LC_ALL" "C")
  really needed here?

- instead of let* and when I’d probably use and-let*.

--
Ricardo

[bug#36875] [PATCH] doc: Document the use of `program-file' for mcron jobs.

[Maxim Cournoyer]

[-- Attachment #1.1: Type: text/plain, Size: 259 bytes --]

Hello!

This follows up to my second post under the thread at
(https://lists.gnu.org/archive/html/help-guix/2019-07/msg00180.html).

It aims to shed some light on (more) complex mcron job Guile scripting
with the aid of Guix features (such as program-file).


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: 0001-doc-Document-the-use-of-program-file-for-mcron-jobs.patch --]
[-- Type: text/x-patch, Size: 2283 bytes --]

From 4d2c5929f056e547b6bd138f69bd1e09e7cfc89f Mon Sep 17 00:00:00 2001
From: Maxim Cournoyer <maxim.cournoyer@gmail.com>
Date: Thu, 1 Aug 2019 07:34:17 +0900
Subject: [PATCH] doc: Document the use of `program-file' for mcron jobs.

* doc/guix.texi (Scheduled Job Execution): Explain why using `program-file'
for an mcron job can be necessary.  Add an example.
---
 doc/guix.texi | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index e6047a4909..418dbce16b 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -12444,6 +12444,41 @@ gexps to introduce job definitions that are passed to mcron
                   %base-services)))
 @end lisp
 
+For more complex jobs defined in Scheme, it is safer to pass the job as a
+script to mcron; otherwise, imported syntax definitions wouldn't work
+correctly, as these must be strictly imported at the top level of a Guile
+module.  This can be achieved using the @code{program-file} procedure from the
+@code{(guix gexp)} module, as shown in the example below.
+
+@lisp
+(define %battery-alert-job
+  ;; Beep the system when the battery reaches %MIN-LEVEL or less
+  ;; battery percent.
+  #~(job
+     '(next-minute (range 0 60 1))
+     #$(program-file
+	"battery-alert.scm"
+	(with-imported-modules (source-module-closure
+				'((guix build utils)))
+	  #~(begin
+	      (define %min-level 20)
+	      (use-modules (guix build utils)
+			   (ice-9 popen)
+			   (ice-9 regex)
+			   (ice-9 textual-ports)
+			   (srfi srfi-26))
+	      (setenv "LC_ALL" "C")
+	      (let* ((input-pipe (open-pipe* OPEN_READ
+					     #$(file-append acpi "/bin/acpi")))
+		     (output (get-string-all input-pipe))
+		     (m (string-match "Discharging, ([0-9]+)%" output))
+		     (level (and=> m (compose string->number
+					      (cut match:substring <> 1)))))
+		(when (and=> level (cut <= <> %min-level))
+		  (format #t "warning: Battery level is low (~a%)~%" level)
+		  (invoke #$(file-append beep "/bin/beep") "-r5"))))))))
+@end lisp
+
 @xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron},
 for more information on mcron job specifications.  Below is the
 reference of the mcron service.
-- 
2.21.0


[-- Attachment #1.3: Type: text/plain, Size: 16 bytes --]


Thanks,

Maxim

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

[bug#36875] [PATCH] doc: Document the use of `program-file' for mcron jobs.

[Maxim Cournoyer]

[-- Attachment #1.1: Type: text/plain, Size: 3954 bytes --]

Hello Ricardo!

Ricardo Wurmus <rekado@elephly.net> writes:

> Hi Maxim,
>
>> This follows up to my second post under the thread at
>> (https://lists.gnu.org/archive/html/help-guix/2019-07/msg00180.html).
>>
>> It aims to shed some light on (more) complex mcron job Guile scripting
>> with the aid of Guix features (such as program-file).
>
> I wonder if this can be worked around some other way, e.g. by adding
> srfi-26 to the “with-imported-modules” clause.

No; srfi-26 is already present in the Guile load
path. `with-imported-modules' is used to import non-builtin Guile
modules into the generated script load paths. In the current example,
passing (srfi srfi-26) to (with-imported-modules ...) doesn't change the
hash of the compiled gexps (because it is already included).

> I don’t fully understand the problem as described in the addition to the
> manual.  What does “imported syntax definitions wouldn't work correctly”
> mean?

That any macro imported with (use-modules ...) in a mcron job defined
using a lambda would not be expanded correctly.

> It would be useful to state that this is something to do with srfi-26.

It is not just about srfi-26; but about any syntax definitions (macros) that a
user might want to use in a mcron script, such as `guard' from
srfi-34. Consider the mcron job defined as below:

--8<---------------cut here---------------start------------->8---
(define %macros-in-a-mcron-lambda-job-dont-work
  (with-imported-modules (source-module-closure
			  '((guix build utils)))
    #~(job
       '(next-minute (range 0 60 1))
       (lambda _
	 (use-modules (guix build utils)
		      (srfi srfi-34))
	 (guard (c ((invoke-error? c))
		   (format #t "Guard worked as expected."))
	   (invoke "false"))))))
--8<---------------cut here---------------end--------------->8---

Then upon running, it would fail with the following backtrace:

--8<---------------cut here---------------start------------->8---
Backtrace:
           9 (apply-smob/1 #<catch-closure 19e7300>)
In ice-9/boot-9.scm:
    829:9  8 (catch _ _ #<procedure 7f858dc5ed38 at mcron/scripts/m?> ?)
In mcron/scripts/mcron.scm:
     99:7  7 (_)
In mcron/base.scm:
   234:12  6 (_ #<continuation 19d3020>)
In srfi/srfi-1.scm:
    640:9  5 (for-each #<procedure run-job (job)> (#<<job> user: #(?>))
In mcron/base.scm:
   186:10  4 (run-job _)
In ice-9/eval.scm:
    159:9  3 (_ #(#(#<directory (mcron scripts mcron) 1ac1c80>) ()))
   182:19  2 (proc #(#(#<directory (mcron scripts mcron) 1ac1c80>) #))
   142:16  1 (compile-top-call _ (7 . c) ((10 (10 (13 15 . #) #)) #))
In unknown file:
           0 (%resolve-variable (7 . c) #<directory (mcron scripts m?>)

ERROR: In procedure %resolve-variable:
Unbound variable: c
--8<---------------cut here---------------end--------------->8---

Which I found quite puzzling, and can easily imagine other mcron users
stumbling onto.  The solution (to use the program-file Gexp facility) is
not an obvious one, so is worth being documented, in my opinion. I've
attempted to clarify the text is the revised patch (attached).

> About the patch:
>
> - please replace tabs with spaces.

Done.

> - “Beep the system when the battery reaches %MIN-LEVEL or less battery
>   percent.” sounds odd.  How about “Beep when the battery percentage
>   falls below %MIN-LEVEL.”?

Done (and modified the logic to match it).
)
> - Can the example be simplified further?  Is (setenv "LC_ALL" "C")
>   really needed here?

It's to ensure that the output of the 'acpi' command is in English,
which the script depends on (setting the locale of the system to
something else could affect this, if acpi is internationalized (I don't
know, but I'm protecting against it, in case)).

> - instead of let* and when I’d probably use and-let*.

Done.

Reworked patch is attached.

Thanks for the feedback! :-)

Maxim

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: 0001-doc-Document-the-use-of-program-file-for-mcron-jobs.patch --]
[-- Type: text/x-patch, Size: 2584 bytes --]

From 0fffed46b4899bf0485926399d3971a4b5e94408 Mon Sep 17 00:00:00 2001
From: Maxim Cournoyer <maxim.cournoyer@gmail.com>
Date: Thu, 1 Aug 2019 07:34:17 +0900
Subject: [PATCH] doc: Document the use of `program-file' for mcron jobs.

* doc/guix.texi (Scheduled Job Execution): Explain why using `program-file'
for an mcron job can be necessary.  Add an example.
---
 doc/guix.texi | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index e6047a4909..dd06efa9c2 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -12444,6 +12444,41 @@ gexps to introduce job definitions that are passed to mcron
                   %base-services)))
 @end lisp
 
+For more complex jobs defined in Scheme, it is safer to pass the job as a
+script to mcron; otherwise, macros defined or imported with @code{use-modules}
+wouldn't expand correctly, as Guile requires macros to be strictly defined or
+imported at the top level of a Guile module.  This can be achieved using the
+@code{program-file} procedure from the @code{(guix gexp)} module, as shown in
+the example below.
+
+@lisp
+(define %battery-alert-job
+  ;; Beep when the battery percentage falls below %MIN-LEVEL.
+  #~(job
+     '(next-minute (range 0 60 1))
+     #$(program-file
+        "battery-alert.scm"
+        (with-imported-modules (source-module-closure
+                                '((guix build utils)))
+          #~(begin
+              (define %min-level 20)
+              (use-modules (guix build utils)
+                           (ice-9 popen)
+                           (ice-9 regex)
+                           (ice-9 textual-ports)
+                           (srfi srfi-2))
+              (setenv "LC_ALL" "C")
+              (and-let* ((input-pipe (open-pipe*
+                                      OPEN_READ
+                                      #$(file-append acpi "/bin/acpi")))
+                         (output (get-string-all input-pipe))
+                         (m (string-match "Discharging, ([0-9]+)%" output))
+                         (level (string->number (match:substring m 1)))
+                         ((< level %min-level)))
+                (format #t "warning: Battery level is low (~a%)~%" level)
+                (invoke #$(file-append beep "/bin/beep") "-r5")))))))
+@end lisp
+
 @xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron},
 for more information on mcron job specifications.  Below is the
 reference of the mcron service.
-- 
2.21.0


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

[bug#36875] [PATCH] doc: Document the use of `program-file' for mcron jobs.

[Ludovic Courtès]

Hello!

Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:

> From 0fffed46b4899bf0485926399d3971a4b5e94408 Mon Sep 17 00:00:00 2001
> From: Maxim Cournoyer <maxim.cournoyer@gmail.com>
> Date: Thu, 1 Aug 2019 07:34:17 +0900
> Subject: [PATCH] doc: Document the use of `program-file' for mcron jobs.
>
> * doc/guix.texi (Scheduled Job Execution): Explain why using `program-file'
> for an mcron job can be necessary.  Add an example.

[...]

> +For more complex jobs defined in Scheme, it is safer to pass the job as a
> +script to mcron; otherwise, macros defined or imported with @code{use-modules}
> +wouldn't expand correctly, as Guile requires macros to be strictly defined or
> +imported at the top level of a Guile module.  This can be achieved using the
> +@code{program-file} procedure from the @code{(guix gexp)} module, as shown in
> +the example below.

Macros are a very good example of the problem, but I wonder if it would
be clearer to simply write something like:

  For more complex jobs defined in Scheme where you need control over
  the top level, for instance to introduce a @code{use-modules} form, you
  can move your code to a separate program using the @code{program-file}
  procedure of the @code{(guix gexp)} module (@pxref{G-Expressions}).
  The example below illustrates that.

Anyway, your patch looks like a great improvement (and a funny example
:-)) so IMO you should push one version or another!

Thanks,
Ludo’.

bug#36875: [PATCH] doc: Document the use of `program-file' for mcron jobs.

[Maxim Cournoyer]

Hello Ludovic!

Ludovic Courtès <ludo@gnu.org> writes:

> Hello!
>
> Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:
>
>> From 0fffed46b4899bf0485926399d3971a4b5e94408 Mon Sep 17 00:00:00 2001
>> From: Maxim Cournoyer <maxim.cournoyer@gmail.com>
>> Date: Thu, 1 Aug 2019 07:34:17 +0900
>> Subject: [PATCH] doc: Document the use of `program-file' for mcron jobs.
>>
>> * doc/guix.texi (Scheduled Job Execution): Explain why using `program-file'
>> for an mcron job can be necessary.  Add an example.
>
> [...]
>
>> +For more complex jobs defined in Scheme, it is safer to pass the job as a
>> +script to mcron; otherwise, macros defined or imported with @code{use-modules}
>> +wouldn't expand correctly, as Guile requires macros to be strictly defined or
>> +imported at the top level of a Guile module.  This can be achieved using the
>> +@code{program-file} procedure from the @code{(guix gexp)} module, as shown in
>> +the example below.
>
> Macros are a very good example of the problem, but I wonder if it would
> be clearer to simply write something like:
>
>   For more complex jobs defined in Scheme where you need control over
>   the top level, for instance to introduce a @code{use-modules} form, you
>   can move your code to a separate program using the @code{program-file}
>   procedure of the @code{(guix gexp)} module (@pxref{G-Expressions}).
>   The example below illustrates that.

I like your version, which feels to me more elegant. But, from my
experimentation, using (use-modules) in a nested form is fine for
anything else than syntax (macros).  Also, the Guile Reference only says
that macros must be *defined* at the top level; it doesn't explicitly
mention that importing macros is equivalent to defining macros, and are
thus subjected to the same restrictions.  So, I've amended it to mention
the problem more precisely:

--8<---------------cut here---------------start------------->8---
For more complex jobs defined in Scheme where you need control over the top
level, for instance to introduce a @code{use-modules} form that defines syntax
(macros), you can move your code to a separate program using the
@code{program-file} procedure of the @code{(guix gexp)} module
(@pxref{G-Expressions}).  The example below illustrates that.
--8<---------------cut here---------------end--------------->8---

> Anyway, your patch looks like a great improvement (and a funny example
> :-)) so IMO you should push one version or another!

This is now live as commit 1407ebeaa1.  Thanks for feedback/review! :-)

Maxim

[bug#36875] [PATCH] doc: Document the use of `program-file' for mcron jobs.

[Ludovic Courtès]

Hi Maxim,

Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:

> Ludovic Courtès <ludo@gnu.org> writes:
>
>> Hello!
>>
>> Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:
>>
>>> From 0fffed46b4899bf0485926399d3971a4b5e94408 Mon Sep 17 00:00:00 2001
>>> From: Maxim Cournoyer <maxim.cournoyer@gmail.com>
>>> Date: Thu, 1 Aug 2019 07:34:17 +0900
>>> Subject: [PATCH] doc: Document the use of `program-file' for mcron jobs.
>>>
>>> * doc/guix.texi (Scheduled Job Execution): Explain why using `program-file'
>>> for an mcron job can be necessary.  Add an example.
>>
>> [...]
>>
>>> +For more complex jobs defined in Scheme, it is safer to pass the job as a
>>> +script to mcron; otherwise, macros defined or imported with @code{use-modules}
>>> +wouldn't expand correctly, as Guile requires macros to be strictly defined or
>>> +imported at the top level of a Guile module.  This can be achieved using the
>>> +@code{program-file} procedure from the @code{(guix gexp)} module, as shown in
>>> +the example below.
>>
>> Macros are a very good example of the problem, but I wonder if it would
>> be clearer to simply write something like:
>>
>>   For more complex jobs defined in Scheme where you need control over
>>   the top level, for instance to introduce a @code{use-modules} form, you
>>   can move your code to a separate program using the @code{program-file}
>>   procedure of the @code{(guix gexp)} module (@pxref{G-Expressions}).
>>   The example below illustrates that.
>
> I like your version, which feels to me more elegant. But, from my
> experimentation, using (use-modules) in a nested form is fine for
> anything else than syntax (macros).

That’s right, but I strongly recommend not relying on non-toplevel
‘use-modules’ because (1) it’s “ugly” because it introduces new bindings
at run time, and (2) it’s not guaranteed to work in the future—in fact,
the just-released Guile 2.9.4 introduces “declarative modules”, which is
probably a first step in the direction of less run-time trickery with
modules.

> This is now live as commit 1407ebeaa1.  Thanks for feedback/review! :-)

Great, thank you!

Ludo’.

[bug#36875] [PATCH] doc: Document the use of `program-file' for mcron jobs.

[Maxim Cournoyer]

Hello Ludovic,

Ludovic Courtès <ludo@gnu.org> writes:

> Hi Maxim,
>
> Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:
>
>> Ludovic Courtès <ludo@gnu.org> writes:
>>
>>> Hello!
>>>
>>> Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:
>>>
>>>> From 0fffed46b4899bf0485926399d3971a4b5e94408 Mon Sep 17 00:00:00 2001
>>>> From: Maxim Cournoyer <maxim.cournoyer@gmail.com>
>>>> Date: Thu, 1 Aug 2019 07:34:17 +0900
>>>> Subject: [PATCH] doc: Document the use of `program-file' for mcron jobs.
>>>>
>>>> * doc/guix.texi (Scheduled Job Execution): Explain why using `program-file'
>>>> for an mcron job can be necessary.  Add an example.

[...]

>>> Macros are a very good example of the problem, but I wonder if it would
>>> be clearer to simply write something like:
>>>
>>>   For more complex jobs defined in Scheme where you need control over
>>>   the top level, for instance to introduce a @code{use-modules} form, you
>>>   can move your code to a separate program using the @code{program-file}
>>>   procedure of the @code{(guix gexp)} module (@pxref{G-Expressions}).
>>>   The example below illustrates that.
>>
>> I like your version, which feels to me more elegant. But, from my
>> experimentation, using (use-modules) in a nested form is fine for
>> anything else than syntax (macros).
>
> That’s right, but I strongly recommend not relying on non-toplevel
> ‘use-modules’ because (1) it’s “ugly” because it introduces new bindings
> at run time, and (2) it’s not guaranteed to work in the future—in fact,
> the just-released Guile 2.9.4 introduces “declarative modules”, which is
> probably a first step in the direction of less run-time trickery with
> modules.

Oh!  That's good to know!  Then using your proposed text as-is makes
even more sense.  Done in commit 4183105de0.

Thank you!

Maxim