bug#56114: Guix does not have a documented general and practical procedure for lowering a single lowerable object to the /gnu/store/... string.

[zimoun]

Hi,

On Mon, 04 Jul 2022 at 22:13, Ludovic Courtès <ludo@gnu.org> wrote:

> I explicitly made “,build” hide that difference; I thought one would
> just want “,build” to do the right thing and display the resulting store
> item regardless of that kind of detail.
>
> Conversely, “,lower” is for die-hard hackers and it doesn’t hide any
> subtlety.

Both make sense. :-)


> Right, that’s because ‘plain-file’ lowers directly to a store item, not
> to a derivation.

My comment was about an unrelated thing.  Well, I do not use every day
G-exp nor ’plain-file’ and the like.  The interface appears to me
unexpected each time I use it but hey I can live with it. :-) However,
the documentation (or docstring) does not appear clear, each time I have
my «aaah right!» moment.  For instance, the manual says:

        The local-file, plain-file, computed-file, program-file, and
        scheme-file procedures below return file-like objects. That is,
        when unquoted in a G-expression, these objects lead to a file in
        the store.

and the docstrings say:

--8<---------------cut here---------------start------------->8---
(define (plain-file name content)
  "Return an object representing a text file called NAME with the given
CONTENT (a string) to be added to the store.

This is the declarative counterpart of 'text-file'."
--8<---------------cut here---------------end--------------->8---

or

--8<---------------cut here---------------start------------->8---
(define* (computed-file name gexp
                        #:key guile (local-build? #t) (options '()))
  "Return an object representing the store item NAME, a file or directory
computed by GEXP.  When LOCAL-BUILD? is #t (the default), it ensures the
corresponding derivation is built locally.  OPTIONS may be used to pass
additional arguments to 'gexp->derivation'.

This is the declarative counterpart of 'gexp->derivation'."
--8<---------------cut here---------------end--------------->8---

when ’plain-file’ and ’computed-file’ does not return the same type of
“file-like object“.  Especially when reading,

--8<---------------cut here---------------start------------->8---
(define* (mixed-text-file name #:key guile #:rest text)
  "Return an object representing store file NAME containing TEXT.  TEXT is a
sequence of strings and file-like objects, as in:

  (mixed-text-file \"profile\"
                   \"export PATH=\" coreutils \"/bin:\" grep \"/bin\")

This is the declarative counterpart of 'text-file*'."
--8<---------------cut here---------------end--------------->8---

it is hard to guess beforehand that ’plain-file’ and ’mixed-text-file’
do not return the same type of file-like object.

Therefore, I was thinking to tweak these docstrings to better underline
their difference.  Well, maybe it is only me. :-)


Cheers,
simon


PS:
It remembers me unrelated [1] mentioning confusion about “file or
file-like object”. :-)

1: 
<https://yhetil.org/guix/CAKjmbcA+PNVCZRnp3oY+P4iAeu4pTvtwUMuVRYk_mFoJpO=jUQ@mail.gmail.com>