[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#56114: Guix does not have a documented general and practical procedu
From: |
zimoun |
Subject: |
bug#56114: Guix does not have a documented general and practical procedure for lowering a single lowerable object to the /gnu/store/... string. |
Date: |
Mon, 04 Jul 2022 23:59:48 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) |
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>
- bug#56114: Guix does not have a documented general and practical procedure for lowering a single lowerable object to the /gnu/store/... string., Ludovic Courtès, 2022/07/03
- bug#56114: Guix does not have a documented general and practical procedure for lowering a single lowerable object to the /gnu/store/... string., zimoun, 2022/07/04
- bug#56114: Guix does not have a documented general and practical procedure for lowering a single lowerable object to the /gnu/store/... string., Ludovic Courtès, 2022/07/04
- bug#56114: Guix does not have a documented general and practical procedure for lowering a single lowerable object to the /gnu/store/... string.,
zimoun <=
- bug#56114: Guix does not have a documented general and practical procedure for lowering a single lowerable object to the /gnu/store/... string., Ludovic Courtès, 2022/07/05
- bug#56114: Guix does not have a documented general and practical procedure for lowering a single lowerable object to the /gnu/store/... string., zimoun, 2022/07/05
- bug#56114: Guix does not have a documented general and practical procedure for lowering a single lowerable object to the /gnu/store/... string., Joshua Branson, 2022/07/10
- bug#56114: Guix does not have a documented general and practical procedure for lowering a single lowerable object to the /gnu/store/... string., Ludovic Courtès, 2022/07/15
- bug#56114: Guix does not have a documented general and practical procedure for lowering a single lowerable object to the /gnu/store/... string., Maxime Devos, 2022/07/19