GNU bug report logs - #53368
.guix-authorizations 'version' field documentation

Previous Next

To reply to this bug, email your comments to 53368 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Christopher Rodriguez <yewscion <at> gmail.com>
To: bug-guix <at> gnu.org
Subject: .guix-authorizations 'version' field documentation
Date: Wed, 19 Jan 2022 09:40:01 -0500

[Message part 1 (text/plain, inline)]

Hey all,

I've just been able to clone my authenticated personal repository for
the first time in a few weeks because I was confusing the `version`
field of `(authorizations …` to be a file version field as opposed to
the version of the API being used.

For clarity, I'm working on a patch that will edit the section of the
manual to clearly specify that this is the API version (will submit
soon). It currently has a comment in the example source that reads
"current file format version", which lead me to this mistake. Nowhere
else in the text is the `version` field mentioned.

However, as a Lisper, I feel as though the symbol itself could easily
be more descriptive by using `api-version` or something similar rather
than just a generic `version`. It would help prevent other newcomers
from going through the confusion I've just had.

What do You think?

-- 

Christopher Rodriguez

[OpenPGP_0x1102102EBE7C3AE4.asc (application/pgp-keys, attachment)]

[OpenPGP_signature (application/pgp-signature, attachment)]

Message #8 received at 53368 <at> debbugs.gnu.org (full text, mbox):

From: Christopher Rodriguez <yewscion <at> gmail.com>
To: 53368 <at> debbugs.gnu.org
Subject: Patch
Date: Wed, 19 Jan 2022 10:09:40 -0500

[Message part 1 (text/plain, inline)]

Here's a quick patch I threw together for the documentation.

-- 
Christopher Rodriguez

[0001-Modified-.guix-authorizations-section-to-clearly-def.patch (text/x-patch, attachment)]

[OpenPGP_0x1102102EBE7C3AE4.asc (application/pgp-keys, attachment)]

[OpenPGP_signature (application/pgp-signature, attachment)]

Message #11 received at 53368 <at> debbugs.gnu.org (full text, mbox):

From: Maxime Devos <maximedevos <at> telenet.be>
To: Christopher Rodriguez <yewscion <at> gmail.com>, 53368 <at> debbugs.gnu.org
Subject: Re: bug#53368: .guix-authorizations 'version' field documentation
Date: Thu, 20 Jan 2022 14:07:50 +0100

[Message part 1 (text/plain, inline)]

Hi,

Christopher Rodriguez schreef op wo 19-01-2022 om 09:40 [-0500]:
> Hey all,
> 
> I've just been able to clone my authenticated personal repository for
> the first time in a few weeks because I was confusing the `version`
> field of `(authorizations …` to be a file version field as opposed to
> the version of the API being used.
> 
> For clarity, I'm working on a patch that will edit the section of the
> manual to clearly specify that this is the API version (will submit
> soon). It currently has a comment in the example source that reads
> "current file format version", which lead me to this mistake. Nowhere
> else in the text is the `version` field mentioned.
> 
> However, as a Lisper, I feel as though the symbol itself could easily
> be more descriptive by using `api-version` or something similar rather
> than just a generic `version`. It would help prevent other newcomers
> from going through the confusion I've just had.
> 
> What do You think?

'version' does denote a file format version.  Calling it an API version
is somewhat inaccurate, because it is not a application _programming_
interface -- you can't write Scheme code in .guix-authorizations,
only S-exps that match the file format.

While it is the version of the file format, it is not the version of
the file, which I believe is were the confusion came from?

Also, changing 'version' to 'api-version' would probably prevent old
versions of Guix (that only recognise 'version') from pulling new
versions of Guix (that would have an 'api-version' in their
.guix-authorizations) (untested).

Greetings,
Maxime.

[signature.asc (application/pgp-signature, inline)]

Message #14 received at 53368 <at> debbugs.gnu.org (full text, mbox):

From: Ludovic Courtès <ludo <at> gnu.org>
To: Maxime Devos <maximedevos <at> telenet.be>
Cc: Christopher Rodriguez <yewscion <at> gmail.com>, 53368 <at> debbugs.gnu.org
Subject: Re: bug#53368: .guix-authorizations 'version' field documentation
Date: Mon, 24 Jan 2022 15:21:49 +0100

Hi,

Maxime Devos <maximedevos <at> telenet.be> skribis:

> 'version' does denote a file format version.  Calling it an API version
> is somewhat inaccurate, because it is not a application _programming_
> interface -- you can't write Scheme code in .guix-authorizations,
> only S-exps that match the file format.
>
> While it is the version of the file format, it is not the version of
> the file, which I believe is were the confusion came from?
>
> Also, changing 'version' to 'api-version' would probably prevent old
> versions of Guix (that only recognise 'version') from pulling new
> versions of Guix (that would have an 'api-version' in their
> .guix-authorizations) (untested).

I agree with everything you wrote.

Christopher, with this in mind, do you think we need a sentence or two
in the manual to clarify what the ‘version’ field is about?

Thanks,
Ludo’.

Message #17 received at 53368 <at> debbugs.gnu.org (full text, mbox):

From: Christopher Rodriguez <yewscion <at> gmail.com>
To: 53368 <at> debbugs.gnu.org
Subject: guix-authorizations documentation
Date: Mon, 24 Jan 2022 09:47:16 -0500

[Message part 1 (text/plain, inline)]

Maxime,

Thank You for the explanation. I think I understand that mechanism 
better now.

> While it is the version of the file format, it is not the version of
> the file, which I believe is were the confusion came from?

This is exactly right, that's where my confusion came from.

Ludovic: I'll amend my patch to more explicitly document the version 
field in this way.

Hopefully, it will be sent here by the end of the day. Thank You both 
for Your help!

--

Christopher Rodriguez

[Message part 2 (text/html, inline)]

[OpenPGP_0x1102102EBE7C3AE4.asc (application/pgp-keys, attachment)]

[OpenPGP_signature (application/pgp-signature, attachment)]

Message #20 received at 53368 <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: Christopher Rodriguez <yewscion <at> gmail.com>
Cc: 53368 <at> debbugs.gnu.org
Subject: Re: bug#53368: .guix-authorizations 'version' field documentation
Date: Fri, 04 Mar 2022 22:47:22 -0500

Hi Christopher,

Christopher Rodriguez <yewscion <at> gmail.com> writes:

> Maxime,
>
> Thank You for the explanation. I think I understand that mechanism
> better now.
>
>> While it is the version of the file format, it is not the version of
>> the file, which I believe is were the confusion came from?
>
> This is exactly right, that's where my confusion came from.
>
> Ludovic: I'll amend my patch to more explicitly document the version
> field in this way.
>
> Hopefully, it will be sent here by the end of the day. Thank You both
> for Your help!

Gentle ping.  If you follow-up, I'll close this in 2 weeks time.

Thank you!

Maxim

Message #25 received at 53368 <at> debbugs.gnu.org (full text, mbox):

From: Christopher Rodriguez <yewscion <at> gmail.com>
To: 53368 <at> debbugs.gnu.org
Subject: Missing needed alsa-plugins
Date: Tue, 22 Mar 2022 22:20:54 -0400

[Message part 1 (text/plain, inline)]

Sending an amended patch; After installing on another machine than my 
daily driver, I found that `alsa-plugins` and `alsa-plugins:pulseaudio` 
were needed for orca-lang to have reliable MIDI output. Going to add 
them as propagated inputs; If there's a better way to do so, please let 
me know.

[OpenPGP_0x1102102EBE7C3AE4.asc (application/pgp-keys, attachment)]

[OpenPGP_signature (application/pgp-signature, attachment)]

Message #28 received at 53368 <at> debbugs.gnu.org (full text, mbox):

From: Christopher Rodriguez <yewscion <at> gmail.com>
To: 53368 <at> debbugs.gnu.org
Cc: Christopher Rodriguez <yewscion <at> gmail.com>
Subject: [PATCH] Amended wording in description of .guix-authorizations file
Date: Tue, 22 Mar 2022 22:42:26 -0400

---

Sorry, got my wires crossed there for a moment. Please disregard the above;
It was meant for a different ticket. Here is a small patch for the
documentation, as requested. What do You think?

 doc/guix.texi | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 44b0f9f1ea..f14642bf89 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -5456,7 +5456,9 @@ for Computer Scientists}} for a great overview.}  The
 @end lisp
 
 Each fingerprint is followed by optional key/value pairs, as in the
-example above.  Currently these key/value pairs are ignored.
+example above.  Currently these key/value pairs are ignored, but this
+may change in the future. The @code{version} field specifies the version
+of the @code{authorizations} file the entry was written for.
 
 This authentication rule creates a chicken-and-egg issue: how do we
 authenticate the first commit?  Related to that: how do we deal with
-- 
2.34.0

Message #31 received at 53368 <at> debbugs.gnu.org (full text, mbox):

From: Christopher Rodriguez <yewscion <at> gmail.com>
To: 53368 <at> debbugs.gnu.org
Cc: Christopher Rodriguez <yewscion <at> gmail.com>
Subject: [PATCH v3] Added orca-lang package
Date: Wed, 23 Mar 2022 10:42:52 -0400

---
> This is broken when cross-compiling, try 'cc-for-target'.
> Additionally, 'outputs' and 'inputs' are unused here.

> Why?

> Why the capital letters? And why mention ‘Esoteric’ in the synopsis and
> description?  Also, it is not actually a programming language, it is
> more an implementation of a language for producing music.

> This is not texinfo markup.

> Personally I'd go with "orca-music".

> I don't think that abbreviations are necessary here, these's enough
> space here.

> Spacing went wrong here, try running "./pre-inst-env guix style" on the
> package.

> This seems rather confusing naming.  Libraries are put in [...]/lib,
> not [...]/share.  Alsso, I think you could drop the 'dest-' prefix
> here.

> Phases do not need to return #f anymore.

All of the above were amended as written in this version of the patch.

> Why are these phases deleted?

Went back and audited the phases I initially deleted; Two remain
deleted in this patch: configure, and check. This is due to the
package not using a configure script, nor having any 'check' defined
for make.

> Why are these propagated?

I've propagated both alsa-plugins and alsa-plugins:pulseaudio because
this package using portmidi for midi output, and needs to load the
`libasound_module_conf_pulse.so` shared library to interface with MIDI
when using `pulseaudio`. Is there another way to do this without
propagating these?

> Where does this revision come from?  This is the first version of orca
> in Guix.

The revision was in my personal channel; I kept bumping the revision
number because I needed to recompile the package, and `guix build -f`
would assume the package was already compiled. I've reverted it to
revision 1.

> "git" is not a version numberr, I suggest "0" instead.
> Also, why is a ‘random’ git commit used instead of an upstream version?

The upstream package at https://git.sr.ht/~rabbits/orca does not have
any tags, let alone version tags. And as near as I can tell, it does
not use semantic versioning at all. I used "git" because of my
experience with rpm packaging; I have changed this to 0 here, to align
with Guix conventions.

> Is it agpl3-only or agpl3+?

It is actually expat; apparently I neglected to update this field when
defining this package. I have fixed this here.

> If you do this, you'll have to add the native-search-paths of ncurses
> to orca-lang, because of https://issues.guix.gnu.org/issue/22138.

Discussed this with maximed on #guix. When I tried to apply
`(package-native-search-paths ncurses)` it introduced a bunch of
undefined variable errors. This may be due to cyclic imports; either
way, it seems to be an issue outside the scope of this package.

I've chosen to instead explicitly define the same native search path
(namely, for TERMINFO_DIRS) as ncurses in this package, to work around
this bug.

Here's the patch. Let me know what else can be improved.

Particularly, I am worried about the name of the binary. It is
currently installed as `orca`, which is (I believe) the same name
given to the binary for the orca screen reader.

Should I change this? And if so, how?


 gnu/packages/music.scm | 57 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/gnu/packages/music.scm b/gnu/packages/music.scm
index 9c8203aa80..1240027050 100644
--- a/gnu/packages/music.scm
+++ b/gnu/packages/music.scm
@@ -6879,3 +6879,60 @@ (define-public musikcube
 streaming audio server.")
     (home-page "https://musikcube.com/")
     (license license:bsd-3)))
+(define-public orca-music
+  (let ((commit "5ba56ca67baae3db140f8b7a2b2fc46bbac5602f") (revision "1"))
+    (package
+      (name "orca-music")
+      ;; No upstream version numbers; Using commit instead.
+      (version (git-version "0" revision commit))
+      (source (origin
+                (method git-fetch)
+                (uri (git-reference
+                      (url "https://git.sr.ht/~rabbits/orca")
+                      (commit commit)))
+                (file-name (git-file-name name version))
+                (sha256
+                 (base32
+                  "1mnhk68slc6g5y5348vj86pmnz90a385jxvm3463fic79k90gckd"))))
+      (build-system gnu-build-system)
+      (arguments
+       `(#:phases (modify-phases %standard-phases
+                    (delete 'configure) ;; No autoconf
+                    (delete 'check) ;; No make check
+                    (replace 'build
+                      (lambda* (#:key inputs outputs #:allow-other-keys)
+                        (setenv "CC"
+                                ,(cc-for-target))
+                        (invoke "make" "release")))
+                    (replace 'install
+                      (lambda* (#:key outputs #:allow-other-keys)
+                        (let* ((out (assoc-ref outputs "out")) (dest-bin (string-append
+                                                                          out
+                                                                          "/bin"))
+                               (share (string-append out "/share"))
+                               (dest-examples (string-append share "/examples"))
+                               (dest-doc (string-append share "/doc")))
+                          (install-file "./build/orca" dest-bin)
+                          (copy-recursively "./examples" dest-examples)
+                          (install-file "./README.md" dest-doc)))))))
+      (inputs (list ncurses portmidi))
+      (native-inputs (list pkg-config))
+      ;; The below are needed as propagated inputs to let orca interact with
+      ;; alsa/pulse MIDI.
+      (propagated-inputs `(("alsa-plugins" ,alsa-plugins) ("alsa-plugins:pulseaudio" ,alsa-plugins
+                                                           "pulseaudio")))
+      (native-search-paths (list
+                             (search-path-specification
+                              (variable "TERMINFO_DIRS")
+                              (files '("share/terminfo")))))
+      (synopsis "musical live-coding environment")
+      (description
+       "This is the C implementation of the ORCΛ language and terminal
+livecoding environment. It's designed to be power efficient. It can handle
+large files, even if your terminal is small.
+
+Orca is not a synthesizer, but a flexible livecoding environment capable of
+sending MIDI, OSC, and UDP to your audio/visual interfaces like Ableton,
+Renoise, VCV Rack, or SuperCollider.")
+      (home-page "https://100r.co/site/orca.html")
+      (license license:expat))))
-- 
2.34.0

Message #34 received at 53368 <at> debbugs.gnu.org (full text, mbox):

From: Maxime Devos <maximedevos <at> telenet.be>
To: Christopher Rodriguez <yewscion <at> gmail.com>, 53368 <at> debbugs.gnu.org
Subject: Re: bug#53368: [PATCH v3] Added orca-lang package
Date: Wed, 23 Mar 2022 16:55:34 +0100

[Message part 1 (text/plain, inline)]

Christopher Rodriguez schreef op wo 23-03-2022 om 10:42 [-0400]:
> > Why are these propagated?
> 
> I've propagated both alsa-plugins and alsa-plugins:pulseaudio because
> this package using portmidi for midi output, and needs to load the
> `libasound_module_conf_pulse.so` shared library to interface with
> MIDI when using `pulseaudio`. Is there another way to do this without
> propagating these?

Use 'wrap-program' to set 'LD_LIBRARY_PATH'.
Also, depending on how exactly orca-music loads alsa-
plugins:pulseaudio, it might (emphasis on might) even be sufficient to
put them in 'inputs'.

Greetings,
Maxime.

[signature.asc (application/pgp-signature, inline)]

Message #37 received at 53368 <at> debbugs.gnu.org (full text, mbox):

From: Maxime Devos <maximedevos <at> telenet.be>
To: Christopher Rodriguez <yewscion <at> gmail.com>, 53368 <at> debbugs.gnu.org
Subject: Re: bug#53368: [PATCH v3] Added orca-lang package
Date: Wed, 23 Mar 2022 16:57:12 +0100

[Message part 1 (text/plain, inline)]

Christopher Rodriguez schreef op wo 23-03-2022 om 10:42 [-0400]:
> > Why are these phases deleted?
> 
> Went back and audited the phases I initially deleted; Two remain
> deleted in this patch: configure, and check. This is due to the
> package not using a configure script, nor having any 'check' defined
> for make.

In that case, you can use #:tests? #false to disable tests:

 (package
   [...]
   (arguments
     (list #:tests? #false
           #:phases ...)))

Greetings,
Maxime.

[signature.asc (application/pgp-signature, inline)]

Message #40 received at 53368 <at> debbugs.gnu.org (full text, mbox):

From: Maxime Devos <maximedevos <at> telenet.be>
To: Christopher Rodriguez <yewscion <at> gmail.com>, 53368 <at> debbugs.gnu.org
Subject: Re: bug#53368: [PATCH v3] Added orca-lang package
Date: Wed, 23 Mar 2022 16:58:08 +0100

[Message part 1 (text/plain, inline)]

Christopher Rodriguez schreef op wo 23-03-2022 om 10:42 [-0400]:
> > "git" is not a version numberr, I suggest "0" instead.
> > Also, why is a ‘random’ git commit used instead of an upstream
> > version?
> 
> The upstream package at https://git.sr.ht/~rabbits/orca does not have
> any tags, let alone version tags. And as near as I can tell, it does
> not use semantic versioning at all. I used "git" because of my
> experience with rpm packaging; I have changed this to 0 here, to
> align with Guix conventions.

Ok, together with the comment you added.

[signature.asc (application/pgp-signature, inline)]

Message #43 received at 53368 <at> debbugs.gnu.org (full text, mbox):

From: Maxime Devos <maximedevos <at> telenet.be>
To: Christopher Rodriguez <yewscion <at> gmail.com>, 53368 <at> debbugs.gnu.org
Subject: Re: bug#53368: [PATCH v3] Added orca-lang package
Date: Wed, 23 Mar 2022 17:03:12 +0100

[Message part 1 (text/plain, inline)]

Christopher Rodriguez schreef op wo 23-03-2022 om 10:42 [-0400]:
> +                        (invoke "make" "release")))

'./tool' looks in the output of 'uname -m' to determine the
architecture to compile for, but this is broken when cross-compiling.
Could this be worked-around, perhaps using 'substitute*' +
'target-x86-64?'?

Greetings,
Maxime.

[signature.asc (application/pgp-signature, inline)]

Message #46 received at 53368 <at> debbugs.gnu.org (full text, mbox):

From: Maxime Devos <maximedevos <at> telenet.be>
To: Christopher Rodriguez <yewscion <at> gmail.com>, 53368 <at> debbugs.gnu.org
Subject: Re: bug#53368: [PATCH v3] Added orca-lang package
Date: Wed, 23 Mar 2022 17:04:22 +0100

[Message part 1 (text/plain, inline)]

Christopher Rodriguez schreef op wo 23-03-2022 om 10:42 [-0400]:
> Discussed this with maximed on #guix.

That's me.

>  When I tried to apply
> `(package-native-search-paths ncurses)` it introduced a bunch of
> undefined variable errors. This may be due to cyclic imports; either
> way, it seems to be an issue outside the scope of this package.

Yes, it's out-of-scope here.  FWIW, I'm now looking into breaking the
import cycle.

[signature.asc (application/pgp-signature, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.