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

[Maxim Cournoyer]

Hello Ricardo!

Ricardo Wurmus <address@hidden> 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

0001-doc-Document-the-use-of-program-file-for-mcron-jobs.patch
Description: Text Data

signature.asc
Description: PGP signature