.guix-authorizations 'version' field documentation

OpenSubmitted by Christopher Rodriguez.
Details
4 participants
  • Ludovic Courtès
  • Maxim Cournoyer
  • Maxime Devos
  • Christopher Rodriguez
Owner
unassigned
Severity
normal
C
C
Christopher Rodriguez wrote on 19 Jan 15:40 +0100
(address . bug-guix@gnu.org)
99e271fa-7b0e-30f6-0613-57e7942826a3@gmail.com
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
Attachment: OpenPGP_signature
C
C
Christopher Rodriguez wrote on 19 Jan 16:09 +0100
Patch
(address . 53368@debbugs.gnu.org)
45cc6702-320e-7680-7dc5-109b55502023@gmail.com
Here's a quick patch I threw together for the documentation.
--
Christopher Rodriguez
From 632435ee888e9c5fc6b1b65811d43e7343e7e172 Mon Sep 17 00:00:00 2001
From: Christopher Rodriguez <yewscion@gmail.com>
Date: Wed, 19 Jan 2022 10:00:23 -0500
Subject: [PATCH] Modified '.guix-authorizations' section to clearly define
version field.

---
doc/guix.texi | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)

Toggle diff (26 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index 28eaf8338c..a071754c54 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -5421,7 +5421,7 @@ for Computer Scientists}} for a great overview.}  The
 ;; Example '.guix-authorizations' file.
 
 (authorizations
- (version 0)               ;current file format version
+ (version 0)                       ;current API version
 
  (("AD17 A21E F8AE D8F1 CC02  DBD9 F8AE D8F1 765C 61E3"
    (name "alice"))
@@ -5432,7 +5432,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} API the file 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
Attachment: OpenPGP_signature
M
M
Maxime Devos wrote on 20 Jan 14:07 +0100
Re: bug#53368: .guix-authorizations 'version' field documentation
9ad77607fe114f55cc6a0d23e31882faa63f3def.camel@telenet.be
Hi,

Christopher Rodriguez schreef op wo 19-01-2022 om 09:40 [-0500]:
Toggle quote (20 lines)
> 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.
-----BEGIN PGP SIGNATURE-----

iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYelephccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7kaBAQDxNZHjCRKixz+I3vAayKrqDOtg
EWytSEBN2wMDqX2qdgEA7+ELR5/LwUc97fUSKu/MsedH3QeD9AC8BphC7LHowA0=
=Orm4
-----END PGP SIGNATURE-----


L
L
Ludovic Courtès wrote on 24 Jan 15:21 +0100
(name . Maxime Devos)(address . maximedevos@telenet.be)
874k5tusci.fsf@gnu.org
Hi,

Maxime Devos <maximedevos@telenet.be> skribis:

Toggle quote (13 lines)
> '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’.
C
C
Christopher Rodriguez wrote on 24 Jan 15:47 +0100
guix-authorizations documentation
(address . 53368@debbugs.gnu.org)
eb874559-de4a-ec86-692a-c337004d6948@gmail.com
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
Attachment: file
Attachment: OpenPGP_signature
M
M
Maxim Cournoyer wrote on 5 Mar 04:47 +0100
Re: bug#53368: .guix-authorizations 'version' field documentation
(name . Christopher Rodriguez)(address . yewscion@gmail.com)(address . 53368@debbugs.gnu.org)
875yot12np.fsf_-_@gmail.com
Hi Christopher,

Christopher Rodriguez <yewscion@gmail.com> writes:

Toggle quote (16 lines)
> 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
L
L
Ludovic Courtès wrote on 8 Mar 09:43 +0100
control message for bug #53368
(address . control@debbugs.gnu.org)
87v8wo96lu.fsf@gnu.org
tags 53368 + moreinfo
quit
C
C
Christopher Rodriguez wrote on 23 Mar 03:20 +0100
Missing needed alsa-plugins
(address . 53368@debbugs.gnu.org)
1f22d8f9-ffae-8168-596c-6adf4c1196bc@gmail.com
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.
Attachment: OpenPGP_signature
C
C
Christopher Rodriguez wrote on 23 Mar 03:42 +0100
[PATCH] Amended wording in description of .guix-authorizations file
(address . 53368@debbugs.gnu.org)(name . Christopher Rodriguez)(address . yewscion@gmail.com)
20220323024226.8199-1-yewscion@gmail.com
---

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(-)

Toggle diff (17 lines)
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
C
C
Christopher Rodriguez wrote on 23 Mar 15:42 +0100
[PATCH v3] Added orca-lang package
(address . 53368@debbugs.gnu.org)(name . Christopher Rodriguez)(address . yewscion@gmail.com)
20220323144252.22915-1-yewscion@gmail.com
---
Toggle quote (25 lines)
> 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.

Toggle quote (2 lines)
> 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.

Toggle quote (2 lines)
> 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?

Toggle quote (3 lines)
> 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.

Toggle quote (3 lines)
> "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/orcadoes 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.

Toggle quote (2 lines)
> 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.

Toggle quote (3 lines)
> 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(+)

Toggle diff (67 lines)
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
M
M
Maxime Devos wrote on 23 Mar 16:55 +0100
7df92d9f1bd30984004a3a03dcb9ae69e6b82f48.camel@telenet.be
Christopher Rodriguez schreef op wo 23-03-2022 om 10:42 [-0400]:
Toggle quote (8 lines)
> > 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.
-----BEGIN PGP SIGNATURE-----

iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYjtC9hccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7tkXAP42iHryyjydvewmmLd/QRisa1l0
Q50oWwjR0QEfqcdMcgD8DjVyjxCBltP079kZtdD4+dGZiR3sFAxsuiD0M5/QoAw=
=r7X8
-----END PGP SIGNATURE-----


M
M
Maxime Devos wrote on 23 Mar 16:57 +0100
b190d9456cfaade7402ad83eefa2fd6a24b045fc.camel@telenet.be
Christopher Rodriguez schreef op wo 23-03-2022 om 10:42 [-0400]:
Toggle quote (7 lines)
> > 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.
-----BEGIN PGP SIGNATURE-----

iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYjtDWBccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7kAKAQCQTSkjAR0iCPnhUEBdkU0z0ELD
9tIBM1LTEyYGQKn7vQD/UgInLeGm3Xs/S6KrqqDcDc1WmaWoha6c7ZlSUUzSgwk=
=ye2M
-----END PGP SIGNATURE-----


M
M
Maxime Devos wrote on 23 Mar 16:58 +0100
1af6334b13b1a426b2c02dd1a54ba611d06e9bba.camel@telenet.be
Christopher Rodriguez schreef op wo 23-03-2022 om 10:42 [-0400]:
Toggle quote (10 lines)
> > "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.
-----BEGIN PGP SIGNATURE-----

iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYjtDkBccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7nJZAQC1+GK956elMFBAn93BYGQfT4lJ
S4kKCic8ehqi3DwKRQEA9cdQ6CUA1irpKs1jMNKKptqJSb6KppTw7l8TTVWNaQA=
=qlgN
-----END PGP SIGNATURE-----


M
M
Maxime Devos wrote on 23 Mar 17:03 +0100
cb9feb7289e0e2fb2f70094d187be12f5e36b9da.camel@telenet.be
Christopher Rodriguez schreef op wo 23-03-2022 om 10:42 [-0400]:
Toggle quote (2 lines)
> +                        (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.
-----BEGIN PGP SIGNATURE-----

iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYjtEwBccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7pcqAQDJLuRIRmNcPgCqx5CgDU/H/sZr
gSnwL8FZW8RIwOcV8wEA5gv+6vDCvgUr3Vqv/0jPs7d1EsM8G+8KI1L74FI6LgU=
=IYym
-----END PGP SIGNATURE-----


M
M
Maxime Devos wrote on 23 Mar 17:04 +0100
560c3b61bc9ff646a85e92a1d98b5734bade3031.camel@telenet.be
Christopher Rodriguez schreef op wo 23-03-2022 om 10:42 [-0400]:
Toggle quote (2 lines)
> Discussed this with maximed on #guix.

That's me.

Toggle quote (5 lines)
> 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.
-----BEGIN PGP SIGNATURE-----

iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYjtFBhccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7jtTAP94HRBLYqCXCpJhDE0UrDAjG7pz
vlb8cliGoAdAJFOp8QD/Xv/l7zPy/GRZh0J4FRSFTyV1AQtZQDOS01HlfpCGxgs=
=NUex
-----END PGP SIGNATURE-----


?