bug#53368: .guix-authorizations 'version' field documentation

bug#53368: .guix-authorizations 'version' field documentation

[Christopher Rodriguez]

[-- Attachment #1.1.1: Type: text/plain, Size: 912 bytes --]

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 #1.1.2: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 4067 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 840 bytes --]

bug#53368: Patch

[Christopher Rodriguez]

[-- Attachment #1.1.1: Type: text/plain, Size: 94 bytes --]

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

-- 
Christopher Rodriguez


[-- Attachment #1.1.2: 0001-Modified-.guix-authorizations-section-to-clearly-def.patch --]
[-- Type: text/x-patch, Size: 1356 bytes --]

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

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 #1.1.3: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 4065 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 840 bytes --]

bug#53368: .guix-authorizations 'version' field documentation

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 1635 bytes --]

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.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

bug#53368: .guix-authorizations 'version' field documentation

[Ludovic Courtès]

Hi,

Maxime Devos <maximedevos@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’.

bug#53368: guix-authorizations documentation

[Christopher Rodriguez]

[-- Attachment #1.1.1.1: Type: text/plain, Size: 508 bytes --]

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 #1.1.1.2: Type: text/html, Size: 1306 bytes --]

[-- Attachment #1.1.2: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 6737 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 840 bytes --]

bug#53368: .guix-authorizations 'version' field documentation

[Maxim Cournoyer]

Hi Christopher,

Christopher Rodriguez <yewscion@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

bug#53368: Missing needed alsa-plugins

[Christopher Rodriguez]

[-- Attachment #1.1.1: Type: text/plain, Size: 303 bytes --]

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 #1.1.2: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 11679 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 840 bytes --]

bug#53368: [PATCH] Amended wording in description of .guix-authorizations file

[Christopher Rodriguez]

---

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

bug#53368: [PATCH v3] Added orca-lang package

[Christopher Rodriguez]

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

bug#53368: [PATCH v3] Added orca-lang package

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 629 bytes --]

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.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

bug#53368: [PATCH v3] Added orca-lang package

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 505 bytes --]

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.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

bug#53368: [PATCH v3] Added orca-lang package

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 572 bytes --]

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.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

bug#53368: [PATCH v3] Added orca-lang package

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 381 bytes --]

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.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

bug#53368: [PATCH v3] Added orca-lang package

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 444 bytes --]

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.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]