[bug#58339,2/2] gnu: Add guix-example.

* gnu/packages/guix-extensions.scm (guix-example): New variable.
---
 gnu/packages/guix-extensions.scm | 39 +++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

Am Donnerstag, dem 06.10.2022 um 18:39 +0200 schrieb zimoun:
> * gnu/packages/guix-extensions.scm (guix-example): New variable.
> ---
>  gnu/packages/guix-extensions.scm | 39
> +++++++++++++++++++++++++++++++-
>  1 file changed, 38 insertions(+), 1 deletion(-)
> 
> diff --git a/gnu/packages/guix-extensions.scm b/gnu/packages/guix-
> extensions.scm
> index 6294c15f3d..6541630ddd 100644
> --- a/gnu/packages/guix-extensions.scm
> +++ b/gnu/packages/guix-extensions.scm
> @@ -19,7 +19,44 @@ (define-module (gnu packages guix-extensions)
>    #:use-module (guix gexp)
>    #:use-module (guix packages)
>    #:use-module (guix build-system trivial)
> -  #:use-module (gnu packages base))
> +  #:use-module (guix build-system guile)
> +  #:use-module (guix git-download)
> +  #:use-module (gnu packages base)
> +  #:use-module (gnu packages package-management))
> +
> +(define-public guix-example
> +  (let ((commit "d600bd742dae9df86e980a25cf1d0ac71ee01438")
> +        (revision "0"))
> +    (package
> +      (name "guix-example")
> +      (version (git-version "0" revision commit))
> +      (source
> +       (origin
> +         (method git-fetch)
> +         (uri (git-reference
> +               (url "https://gitlab.com/zimoun/guix-example")
> +               (commit commit)))
> +         (file-name (string-append name version "-checkout"))
> +         (sha256
> +          (base32
> +          
> "0s48b5a1i0vkx5lq7jn9b46zzqv2g3dli7b54sd9365dszqjqzmx"))))
> +      (build-system guile-build-system)
> +      (arguments
> +       '(#:phases (modify-phases %standard-phases
> +                    (add-after 'install 'move-to-extension-directory
> +                      (lambda* (#:key outputs #:allow-other-keys)
> +                        (let* ((out (assoc-ref outputs "out"))
> +                               (target (string-append
> +                                        out
> +                                       
> "/share/guix/extensions/example.scm")))
> +                          (mkdir-p (dirname target))
> +                          (rename-file (car (find-files out
> "example.scm"))
> +                                       target)))))))
> +      (native-inputs (list (lookup-package-input guix "guile")
> guix))
> +      (home-page "") ; Should be documentation location for
> GUIX_EXTENSIONS_PATH
Note that this example has a home-page.
> +      (synopsis "Example of Guix sub-command extension")
> +      (description "This Guix extension provides a simple example to
> extend Guix subcommands.")
> +      (license license:gpl3+))))
While Ludo said "Maybe we should just keep it as an example in the
source tree?", I'm really not sure whether that's the best course of
action.  It will simultaneously act as a package that users won't know
how to use (as evidenced by some people now and then asking how to run
gwl) *and* as not that great of an example on how to write extension,
because people only have the history of the Guix repo to go by.

For a proper guide, I think we should walk through:

1. Writing a sample extension (e.g. one simply printing hello world)
2. Testing the extension via `guix shell'
3. (Pointers on) submitting the extension to Guix proper or managing it
in one's own channel

For now, we barely cover 1.

Cheers

Hi Liliana,

Thanks for your feedback.

On jeu., 06 oct. 2022 at 21:58, Liliana Marie Prikler <liliana.prikler@gmail.com> wrote:

About this:

> 2. Testing the extension via `guix shell'

We need to open another issue because it is not related to the current
patch (proposal for a simple example of an extensions); this point #2 is
an issue about all the extensions.

For instance, let consider guix-modules [1].  It reads,

--8<---------------cut here---------------start------------->8---
$ guix install guix-modules
$ export GUIX_EXTENSIONS_PATH="$HOME/.guix-profile/share/guix/extensions"
--8<---------------cut here---------------end--------------->8---

and if instead, one uses a shell, it fails:

--8<---------------cut here---------------start------------->8---
$ guix shell guix-modules -- guix module -h
guix: module: command not found
Try `guix --help' for more information.

$ guix shell guix-modules
[env]$ guix module -h
guix: module: command not found
Try `guix --help' for more information.
--8<---------------cut here---------------end--------------->8---

Note that the variable GUIX_EXTENSIONS_PATH is listed in etc/profile,

--8<---------------cut here---------------start------------->8---
[env]$ cat $GUIX_ENVIRONMENT/etc/profile
# Source this file to define all the relevant environment variables in Bash
# for this profile.  You may want to define the 'GUIX_PROFILE' environment
# variable to point to the "visible" name of the profile, like this:
#
#  GUIX_PROFILE=/path/to/profile ; \
#  source /path/to/profile/etc/profile
#
# When GUIX_PROFILE is undefined, the various environment variables refer
# to this specific profile generation.

export GUIX_EXTENSIONS_PATH="${GUIX_PROFILE:-/gnu/store/qhfy9wwzg98a0j3i88qaxdmy19rvp0s8-profile}/share/guix/extensions${GUIX_EXTENSIONS_PATH:+:}$GUIX_EXTENSIONS_PATH"
--8<---------------cut here---------------end--------------->8---

Well, another issue with extensions. :-)

1:
<https://hpc.guix.info/blog/2022/05/back-to-the-future-modules-for-guix-packages/>


Cheers,
simon

Am Freitag, dem 07.10.2022 um 10:21 +0200 schrieb zimoun:
> Hi Liliana,
> 
> Thanks for your feedback.
> 
> On jeu., 06 oct. 2022 at 21:58, Liliana Marie Prikler
> <liliana.prikler@gmail.com> wrote:
> 
> About this:
> 
> > 2. Testing the extension via `guix shell'
> 
> We need to open another issue because it is not related to the
> current patch (proposal for a simple example of an extensions); this
> point #2 is an issue about all the extensions.
But that's the point.  Simply adding an extension – whether an example
or an actually useful one – doesn't teach users how to use them.  It's
missing this very information among other things.

> For instance, let consider guix-modules [1].  It reads,
> 
> --8<---------------cut here---------------start------------->8---
> $ guix install guix-modules
> $ export GUIX_EXTENSIONS_PATH="$HOME/.guix-
> profile/share/guix/extensions"
> --8<---------------cut here---------------end--------------->8---
> 
> and if instead, one uses a shell, it fails:
> 
> --8<---------------cut here---------------start------------->8---
> $ guix shell guix-modules -- guix module -h
> guix: module: command not found
> Try `guix --help' for more information.
> 
> $ guix shell guix-modules
> [env]$ guix module -h
> guix: module: command not found
> Try `guix --help' for more information.
> --8<---------------cut here---------------end--------------->8---
> 
> Note that the variable GUIX_EXTENSIONS_PATH is listed in etc/profile,
> 
> --8<---------------cut here---------------start------------->8---
> [env]$ cat $GUIX_ENVIRONMENT/etc/profile
> # Source this file to define all the relevant environment variables
> in Bash
> # for this profile.  You may want to define the 'GUIX_PROFILE'
> environment
> # variable to point to the "visible" name of the profile, like this:
> #
> #  GUIX_PROFILE=/path/to/profile ; \
> #  source /path/to/profile/etc/profile
> #
> # When GUIX_PROFILE is undefined, the various environment variables
> refer
> # to this specific profile generation.
> 
> export GUIX_EXTENSIONS_PATH="${GUIX_PROFILE:-
> /gnu/store/qhfy9wwzg98a0j3i88qaxdmy19rvp0s8-
> profile}/share/guix/extensions${GUIX_EXTENSIONS_PATH:+:}$GUIX_EXTENSI
> ONS_PATH"
> --8<---------------cut here---------------end--------------->8---
> 
> Well, another issue with extensions. :-)
In case you really didn't know how to use extensions with guix shell,
it's guix shell guix your-extension -- guix blah, assuming your
extension works with a slightly older guix.

Cheers

Hi Liliana,

Well, I am in favor to go one foot then the other. :-)  Let start to
have a simple extension that we can improve by incremental changes,
then let add a section in the manual for having the reference
documentation, then let add a cookbook entry, etc.  Well, somehow the
perfect is the enemy of the good. :-)

It appears to me more motivational to document Guix extensions step by
step, i.e., people can contribute to the improvements, etc..  Instead
of going my way alone and then come back with a complete work.  For
what my opinion is worth.


On Fri, 7 Oct 2022 at 20:21, Liliana Marie Prikler
<liliana.prikler@gmail.com> wrote:

> But that's the point.  Simply adding an extension – whether an example
> or an actually useful one – doesn't teach users how to use them.  It's
> missing this very information among other things.

The answer of this is provided by the following part of my previous message. :-)


> > For instance, let consider guix-modules [1].  It reads,
> >
> > --8<---------------cut here---------------start------------->8---
> > $ guix install guix-modules
> > $ export GUIX_EXTENSIONS_PATH="$HOME/.guix-
> > profile/share/guix/extensions"
> > --8<---------------cut here---------------end--------------->8---

The already included extension 'guix-modules' is usable using the
snippet above.  And we teach people via a blog post on hpc.guix.info.


> > --8<---------------cut here---------------start------------->8---
> > $ guix shell guix-modules -- guix module -h
> > guix: module: command not found
> > Try `guix --help' for more information.
> >
> > $ guix shell guix-modules
> > [env]$ guix module -h
> > guix: module: command not found
> > Try `guix --help' for more information.
> > --8<---------------cut here---------------end--------------->8---

> In case you really didn't know how to use extensions with guix shell,
> it's guix shell guix your-extension -- guix blah, assuming your
> extension works with a slightly older guix.

As shown by my snippet above, it does not work; at least on foreign distro.

Cheers,
simon

Am Freitag, dem 07.10.2022 um 20:49 +0200 schrieb zimoun:
> Let start to have a simple extension that we can improve by
> incremental changes,
My point is that we already have proper extensions in both guix and
other channels.  It's a little late to "start with a simple [one]".

> On Fri, 7 Oct 2022 at 20:21, Liliana Marie Prikler
> <liliana.prikler@gmail.com> wrote:
> 
> > But that's the point.  Simply adding an extension – whether an
> > example or an actually useful one – doesn't teach users how to use
> > them.  It's missing this very information among other things.
> 
> The answer of this is provided by the following part of my previous
> message. :-)
I might be missing it or perhaps I disagree.  Pick whichever makes
sense to you after reading this mail.

> > > For instance, let consider guix-modules [1].  It reads,
> > > 
> > > --8<---------------cut here---------------start------------->8---
> > > $ guix install guix-modules
> > > $ export GUIX_EXTENSIONS_PATH="$HOME/.guix-
> > > profile/share/guix/extensions"
> > > --8<---------------cut here---------------end--------------->8---
> 
> The already included extension 'guix-modules' is usable using the
> snippet above.  And we teach people via a blog post on hpc.guix.info.
A manual is clearly more visible than a blog post.  Also, even if that
blog post had everything, we've added blog posts to the cookbook
already, so it wouldn't even be that hard in this case.

> > > --8<---------------cut here---------------start------------->8---
> > > $ guix shell guix-modules -- guix module -h
> > > guix: module: command not found
> > > Try `guix --help' for more information.
> > > 
> > > $ guix shell guix-modules
> > > [env]$ guix module -h
> > > guix: module: command not found
> > > Try `guix --help' for more information.
> > > --8<---------------cut here---------------end--------------->8---
> 
> > In case you really didn't know how to use extensions with guix
> > shell, it's guix shell guix your-extension -- guix blah, assuming
> > your extension works with a slightly older guix.
> 
> As shown by my snippet above, it does not work; at least on foreign
> distro.
Look at your snippet, then back to mine, now back to your snippet, now
back to mine.  Sadly, your snippet isn't mine, but it could be mine if
you added "guix" to the the packages listed before the --.

Cheers

Hi Liliana,

What are we discussing if we are agreeing? ;-)

Well, from my understanding, we are miscommunicating and somehow just
saying the same thing using a different point of view.


On Fri, 07 Oct 2022 at 21:28, Liliana Marie Prikler <liliana.prikler@gmail.com> wrote:
> Am Freitag, dem 07.10.2022 um 20:49 +0200 schrieb zimoun:

>> Let start to have a simple extension that we can improve by
>> incremental changes,
>
> My point is that we already have proper extensions in both guix and
> other channels.  It's a little late to "start with a simple [one]".

What others do I miss?  I am only aware of gwl and guix-modules.

What are the other extensions and from which channels?


>> The already included extension 'guix-modules' is usable using the
>> snippet above.  And we teach people via a blog post on hpc.guix.info.
>
> A manual is clearly more visible than a blog post.  Also, even if that
> blog post had everything, we've added blog posts to the cookbook
> already, so it wouldn't even be that hard in this case.

We agree, I guess.  Maybe it was poorly worded but I was saying that the
current situation is not satisfying and these patches are a tiny first
step in improving the situation.  Yes the manual is the location for the
documentation and that’s some coming patches. :-)

From my understanding, we are saying the same thing. :-)


>> > > --8<---------------cut here---------------start------------->8---
>> > > $ guix shell guix-modules -- guix module -h
>> > > guix: module: command not found
>> > > Try `guix --help' for more information.
>> > > 
>> > > $ guix shell guix-modules
>> > > [env]$ guix module -h
>> > > guix: module: command not found
>> > > Try `guix --help' for more information.
>> > > --8<---------------cut here---------------end--------------->8---
>> 
>> > In case you really didn't know how to use extensions with guix
>> > shell, it's guix shell guix your-extension -- guix blah, assuming
>> > your extension works with a slightly older guix.
>> 
>> As shown by my snippet above, it does not work; at least on foreign
>> distro.
>
> Look at your snippet, then back to mine, now back to your snippet, now
> back to mine.  Sadly, your snippet isn't mine, but it could be mine if
> you added "guix" to the the packages listed before the --.

Maybe I am wrong or maybe I miss a point but rely on the package ’guix’
is not an option for an extension.  We had some discussions [1] about
that on gwl-devel some time ago – which leads to GUIX_EXTENSION_PATH. :-)

Consider,

    guix shell guix <whatever> -- guix <something>

then two revisions of Guix are involved:

  1. one by ~/.config/current/bin/guix calling the subcommand ’shell’
  2. one by ’-- guix <something>’ provided here by the package ’guix’

When an user runs an extension, they expect to run their current Guix.
For instance, consider that ’name-version’ is an extension displaying
name and version.

--8<---------------cut here---------------start------------->8---
(define-module (guix extensions name-version)
  #:use-module (guix scripts)
  #:use-module (guix ui)
  #:use-module (guix packages)
  #:use-module (gnu packages)
  #:export (guix-name-version))

(define-command (guix-name-version . args)
  (category extension)
  (synopsis "show name and version")

  (let* ((pkg (car args))
         (package (specification->package pkg))
         (name (package-name package))
         (version (package-version package)))
    (format #t (G_ "name: ~a~%version: ~a~%") name version)))
--8<---------------cut here---------------end--------------->8---

Using Guix 65cabb0, the use of this extension reads,

--8<---------------cut here---------------start------------->8---
$ GUIX_EXTENSIONS_PATH=/tmp/name-version/guix/extensions guix name-version parallel
name: parallel
version: 20220722

$ guix shell guix
[env]$ GUIX_EXTENSIONS_PATH=/tmp/name-version/guix/extensions guix name-version parallel
name: parallel
version: 20220522
--8<---------------cut here---------------end--------------->8---

There is no difference with an extension and a proper module once
configured GUIX_EXTENSIONS_PATH adequately.  So, equivalently:

--8<---------------cut here---------------start------------->8---
$ guix show parallel | recsel -p name,version
name: parallel
version: 20220722

$ guix shell guix -- guix show parallel | recsel -p name,version
name: parallel
version: 20220522
--8<---------------cut here---------------end--------------->8---

That’s why the package guix is not provided (before --) by the snippets
above.  It is not a mistake and I still maintain there is an unexpected
behaviour (bug?) for the extensions and ’guix shell’ – the fix you are
proposing does not match the idea behind the extensions, IMHO.

BTW, shell+extension is a corner case from my point of view.  I also
maintain it is unrelated to this patch submission. :-)



From the feedback I got at the lightening talk in 10 years event, I
assume the feature is barely known.  I still miss what is the concrete
objection with these patches.  Could you elaborate?  Do they break
something?  Are they not compliant?

I got it, you find them useless. :-) But as I said, maybe I or someone
else will improve next – is perfection not the enemy of the good?

The two only Guix extensions I am aware of are ’gwl’ and ’guix-modules’.
Both are complex and difficult starters, IMHO.  Hence these tiny starter
examples, for what they are worth.

I am fine to expand ’guix-example’, write a section to the manual, etc.
That’s the general idea with the submission of this patch. :-) Well, I
am just missing the objections because these patches appears to me
complementary and a first tiny step.


Cheers,
simon


1: <https://yhetil.org/guix/875zh3w3yp.fsf@elephly.net/>

Am Samstag, dem 08.10.2022 um 10:35 +0200 schrieb zimoun:
> Hi Liliana,
> 
> What are we discussing if we are agreeing? ;-)
> 
> Well, from my understanding, we are miscommunicating and somehow just
> saying the same thing using a different point of view.
> 
> 
> On Fri, 07 Oct 2022 at 21:28, Liliana Marie Prikler
> <liliana.prikler@gmail.com> wrote:
> > Am Freitag, dem 07.10.2022 um 20:49 +0200 schrieb zimoun:
> 
> > > Let start to have a simple extension that we can improve by
> > > incremental changes,
> > 
> > My point is that we already have proper extensions in both guix and
> > other channels.  It's a little late to "start with a simple [one]".
> 
> What others do I miss?  I am only aware of gwl and guix-modules.
> 
> What are the other extensions and from which channels?
Oh, guix-modules is included in Guix proper.  I thought it was part of
an HPC channel, my bad.

> > > The already included extension 'guix-modules' is usable using the
> > > snippet above.  And we teach people via a blog post on
> > > hpc.guix.info.
> > 
> > A manual is clearly more visible than a blog post.  Also, even if
> > that blog post had everything, we've added blog posts to the
> > cookbook already, so it wouldn't even be that hard in this case.
> 
> We agree, I guess.  Maybe it was poorly worded but I was saying that
> the current situation is not satisfying and these patches are a tiny
> first step in improving the situation.  Yes the manual is the
> location for the documentation and that’s some coming patches. :-)
> 
> From my understanding, we are saying the same thing. :-)
From my understanding we are not.  Or at least not under the assumption
that you're saying that adding example extensions will somehow improve
the situation.  Again, we already have actual extensions packaged, I
don't see what the point would be in having an example one.

> > > > > --8<---------------cut here---------------start-------------
> > > > > >8---
> > > > > $ guix shell guix-modules -- guix module -h
> > > > > guix: module: command not found
> > > > > Try `guix --help' for more information.
> > > > > 
> > > > > $ guix shell guix-modules
> > > > > [env]$ guix module -h
> > > > > guix: module: command not found
> > > > > Try `guix --help' for more information.
> > > > > --8<---------------cut here---------------end---------------
> > > > > >8---
> > > 
> > > > In case you really didn't know how to use extensions with guix
> > > > shell, it's guix shell guix your-extension -- guix blah,
> > > > assuming
> > > > your extension works with a slightly older guix.
> > > 
> > > As shown by my snippet above, it does not work; at least on
> > > foreign distro.
> > 
> > Look at your snippet, then back to mine, now back to your snippet,
> > now back to mine.  Sadly, your snippet isn't mine, but it could be
> > mine if you added "guix" to the the packages listed before the --.
> 
> Maybe I am wrong or maybe I miss a point but rely on the package
> ’guix’ is not an option for an extension.  We had some discussions
> [1] about that on gwl-devel some time ago – which leads to
> GUIX_EXTENSION_PATH. :-)
IIUC this discussion is only tangentially related to what we're
discussing now.  At the time of writing, only the guix package provides
GUIX_EXTENSION_PATH as a search path -- similar to how glib is one of
the few packages to provide XDG_DATA_DIRS.  

> Consider,
> 
>     guix shell guix <whatever> -- guix <something>
> 
> then two revisions of Guix are involved:
> 
>   1. one by ~/.config/current/bin/guix calling the subcommand ’shell’
>   2. one by ’-- guix <something>’ provided here by the package ’guix’
> 
> When an user runs an extension, they expect to run their current
> Guix.  For instance, consider that ’name-version’ is an extension
> displaying name and version.
> 
> --8<---------------cut here---------------start------------->8---
> (define-module (guix extensions name-version)
>   #:use-module (guix scripts)
>   #:use-module (guix ui)
>   #:use-module (guix packages)
>   #:use-module (gnu packages)
>   #:export (guix-name-version))
> 
> (define-command (guix-name-version . args)
>   (category extension)
>   (synopsis "show name and version")
> 
>   (let* ((pkg (car args))
>          (package (specification->package pkg))
>          (name (package-name package))
>          (version (package-version package)))
>     (format #t (G_ "name: ~a~%version: ~a~%") name version)))
> --8<---------------cut here---------------end--------------->8---
> 
> Using Guix 65cabb0, the use of this extension reads,
> 
> --8<---------------cut here---------------start------------->8---
> $ GUIX_EXTENSIONS_PATH=/tmp/name-version/guix/extensions guix name-
> version parallel
> name: parallel
> version: 20220722
> 
> $ guix shell guix
> [env]$ GUIX_EXTENSIONS_PATH=/tmp/name-version/guix/extensions guix
> name-version parallel
> name: parallel
> version: 20220522
> --8<---------------cut here---------------end--------------->8---
> 
> There is no difference with an extension and a proper module once
> configured GUIX_EXTENSIONS_PATH adequately.  So, equivalently:
> 
> --8<---------------cut here---------------start------------->8---
> $ guix show parallel | recsel -p name,version
> name: parallel
> version: 20220722
> 
> $ guix shell guix -- guix show parallel | recsel -p name,version
> name: parallel
> version: 20220522
> --8<---------------cut here---------------end--------------->8---
> 
> That’s why the package guix is not provided (before --) by the
> snippets above.  It is not a mistake and I still maintain there is an
> unexpected behaviour (bug?) for the extensions and ’guix shell’ – the
> fix you are proposing does not match the idea behind the extensions,
> IMHO.
> 
> BTW, shell+extension is a corner case from my point of view.  I also
> maintain it is unrelated to this patch submission. :-)
To be fair, the actual bug here is -- as I've said in a number of
patches already -- that manifests don't have first-class search paths.
Were it not for that, you could do guix shell normally.

However, this difference in package versions, while visible, should not
be something a *simple* extension needs to care about.  Plus, I think
people have mentioned the "extensions as channels" pattern, which I
believe is what Andrew was using for Guix Home before it became
upstreamed (and might still be using).

> From the feedback I got at the lightening talk in 10 years event, I
> assume the feature is barely known.  I still miss what is the
> concrete objection with these patches.  Could you elaborate?  Do they
> break something?  Are they not compliant?
> 
> I got it, you find them useless. :-) But as I said, maybe I or
> someone else will improve next – is perfection not the enemy of the
> good?
> 
> The two only Guix extensions I am aware of are ’gwl’ and ’guix-
> modules’.  Both are complex and difficult starters, IMHO.  Hence
> these tiny starter examples, for what they are worth.
> 
> I am fine to expand ’guix-example’, write a section to the manual,
> etc.  That’s the general idea with the submission of this patch. :-)
> Well, I am just missing the objections because these patches appears
> to me complementary and a first tiny step.
I reject the idea of including examples that are strictly less
explanatory than GNU hello -- which imho all the hitherto proposed ones
are -- as packages to install solely on the ground that gwl and guix-
modules are "complex and difficult starters".  Of course, they are
complex by the nature of the real-world problems they are trying to
solve, but that doesn't mean there are no real-world problems with
simpler solutions.

The work a novice user would have to do to understand all of guix-
example would be to `guix build -S guix-example', then understand its
code, followed by `guix edit guix-example', understand that, and
finally apply it to their use case.  Note how this includes commands
that are typically more on the contributor side.  Also note how the
code is splintered in two segments so they have to switch between the
two (or it's tangled as in the case of guix-hello, which also has its
issues).  The cookbook on the other hand can be read with the info
reader (or browser) of their choice, and is thus imho preferable.  It
also offers a better way of putting the code together without literally
writing the extension code inside the package itself.

Cheers