* Guix CLI, thoughts and suggestions
@ 2024-01-15 19:24 Ian Eure
2024-01-15 21:01 ` Felix Lechner via Development of GNU Guix and the GNU System distribution.
` (2 more replies)
0 siblings, 3 replies; 8+ messages in thread
From: Ian Eure @ 2024-01-15 19:24 UTC (permalink / raw)
To: guix-devel
Greetings,
As I’ve been learning Guix, one of the things I’ve found somewhat
unpleasant is the lack of consistency within the guix CLI tool.
It feels a bit Git-like, with not much consistency, commands that
non-obvioulsy perform more than operation, related commands in
different places in the tree, etc.
Just so you know where I’m coming from: I’ve found that compliex
CLI tooling benefits from organization and consistency. The Linux
ip(8) command is a good example of this kind of organization: to
add an IP address, you use `ip address add'. To show address, `ip
address show', and to remove one `ip address del'. When options
are needed, they get added after the verb or branch in the verb
tree; the final verb may take positional arguments as well as
--long or -s (short)-form options.
Some examples of where I think Guix could do better. This is an
illustrative list, not an exhaustive one.
Inconsistent organization
=========================
Most package-related commands are under `guix package', but many
are sibling commands. Examples are `guix size', `guix lint',
`guix hash', etc.
Inconsistency between verbs and options
=======================================
Some verbs are bare-word positional arguments, and others are
flags to related verbs. IMO, this is the biggest problem, and
makes it very difficult to find all the things the CLI can do.
`guix package' is a major offender in this area, as it mixes verbs
and verb-specific options into the same level. For example,
installing a package is `guix package -i foo' rather than `guix
package install foo', removing is `guix package -r foo' rather
than `guix package remove foo', and listing installed packages is
`guix package -I' rather than `guix package installed' (or
similar).
This means that users can express commands which *seem* like they
should work, but do not. For example `guix package -i emacs -r
emacs-pgtk -I' represents a command to 1) install emacs 2) remove
emacs-pgtk 3) list installed packages (which would verify the
previous two operations occurred). This is a valid command within
the accepted organization of `guix package', and doesn’t cause an
error, but doesn’t work: the install and remove steps are ignored.
A thing I’ve found throughout my career is that designing systems
so it’s *impossible* to represent unsupported, nonsensical, or
undefined things is an extremely valuable technique to avoid
errors and pitfalls. I think Guix could get a lot of mileage out
of adopting something similar.
This causes a related problem of making it impossible to know what
options are valid for what verbs. Will `guix package --cores=8 -r
emacs' remove the package while using eight cores of my system?
Will `guix system -s i686 switch-generation 5' switch me to a
32-bit version of generation 5? If verbs are organized better,
and have their own options, this ambiguity vanishes.
More inconsistency
==================
Other parts of guix have the opposite problem: `guix system
docker-image' probably ought to be an option to `guix system
image' rather than a separate verb.
Inconsistency between similar commands
======================================
There are generations of both the system (for GuixSD) and the user
profile, however, they work differently. For the system, there’s
`guix system list-generations' and `guix system
switch-generation', but for the user profile, you need `guix
package --list-generations' and `guix package
--switch-generation=PATTERN'. Additionally, no help is available
for either of the system commands: `guix system switch-generations
--help' gives the same output as `guix system --help' -- no
description of the supported ways of expressing a generation are
available.
Flattened verbs
===============
Related, the generation-related commands under `guix system' ought
to be one level deeper: `guix system generation list', `guix
system generation switch' etc.
Repeated options
================
Many commands (`guix package', `guix system', `guix build', `guix
shell') take -L options, to add Guile source to their load-path.
This probably ought to be an option to guix itself, so you can do
`guix -L~/src/my-channel build ...'.
Suggestions
===========
All commands should be organized into a tree of verbs.
Verbs should have common aliases (`rm' for `remove', etc).
Verbs should be selected by specifying the minimum unambiguous
substring. For example `guix sys gen sw' could refer to `guix
system generation switch'.
Options should be applicable to each level of the tree, ex `guix
-L~/src/my-channel' would add that load-path, which would be
visible to any command.
Requesting help is a verb. Appending "help" to any level of the
verb tree should show both options applicable to that verb, and
its child verbs. `guix help' would show global options and all
top-level verbs (package, system, generation, etc); `guix package
help' would show package-specific options and package-specific
verbs; and so on.
Conclusion
==========
I have no idea if anyone feels similarly about this, or whether
there’s appetite to change the CLI, but I think it’d be time
well-spent. Having some kind of agreed-upon standard for how the
CLI stuff is organized seems like a good thing to me, even if it
just stops or slows the addition of more commands with unique
expressions.
It seems like a lot of work to change, and backwards compatibility
also is an issue. One option I could see working is shoving the
entire existing structure under a command in the new tool, so you
could do `guix old package -I' or similar. An alternate approach
would be using an environment variable to change behaviors.
What do you all think?
Thanks,
— Ian
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Guix CLI, thoughts and suggestions
2024-01-15 19:24 Guix CLI, thoughts and suggestions Ian Eure
@ 2024-01-15 21:01 ` Felix Lechner via Development of GNU Guix and the GNU System distribution.
2024-01-15 22:08 ` Carlo Zancanaro
2024-01-17 7:21 ` Efraim Flashner
2 siblings, 0 replies; 8+ messages in thread
From: Felix Lechner via Development of GNU Guix and the GNU System distribution. @ 2024-01-15 21:01 UTC (permalink / raw)
To: Ian Eure, guix-devel
Hi Ian,
On Mon, Jan 15 2024, Ian Eure wrote:
> What do you all think?
The pain is not yet great enough to make changes.
Also, the interface may have more basic issues. [1]
Kind regards
Felix
[1] https://issues.guix.gnu.org/58908
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Guix CLI, thoughts and suggestions
2024-01-15 19:24 Guix CLI, thoughts and suggestions Ian Eure
2024-01-15 21:01 ` Felix Lechner via Development of GNU Guix and the GNU System distribution.
@ 2024-01-15 22:08 ` Carlo Zancanaro
2024-01-20 22:50 ` Ian Eure
2024-01-17 7:21 ` Efraim Flashner
2 siblings, 1 reply; 8+ messages in thread
From: Carlo Zancanaro @ 2024-01-15 22:08 UTC (permalink / raw)
To: Ian Eure; +Cc: guix-devel
Hi Ian,
Much of what you've written is fair, and I'm sure that Guix's commands
could be better organised. I'm not really involved in Guix development,
but I think there are two "inconsistencies" that you've mentioned which
can be explained.
On Mon, Jan 15 2024, Ian Eure wrote:
> Some examples of where I think Guix could do better. This is an
> illustrative list, not an exhaustive one.
>
> Inconsistent organization
> =========================
>
> Most package-related commands are under `guix package', but many are
> sibling commands. Examples are `guix size', `guix lint', `guix hash',
> etc.
I think the real inconsistency here is that `guix package' is poorly
named. This command really operates on profiles, and performs operations
(install, remove, list, etc.) on those profiles. Packages are given as
arguments to this command.
The other commands operate on, and show the properties of, packages.
Similarly with `guix build'.
> Inconsistency between verbs and options
> =======================================
> ... For example, installing a package is `guix package -i foo' rather
> than `guix package install foo', removing is `guix package -r foo'
> rather than `guix package remove foo', and listing installed packages
> is `guix package -I' rather than `guix package installed' (or
> similar).
The specific example of `guix package' might be explained by considering
it as a single transaction to update the profile. The command `guix
package' really says "perform a transaction on the profile", and the
options are the commands in the transaction. Since there can be multiple
commands, and the command names look like package names, they are
provided as options.
This doesn't fully explain the behaviour. In particular the example you
give:
> This means that users can express commands which *seem* like they
> should work, but do not. For example `guix package -i emacs -r
> emacs-pgtk -I' represents a command to 1) install emacs 2) remove
> emacs-pgtk 3) list installed packages (which would verify the previous
> two operations occurred). ...
seems reasonable to have working within the view of `guix package' as a
transactional operation.
It's also worth noting that there are convenience shortcuts in `guix
install' and `guix remove'.
> It seems like a lot of work to change, and backwards compatibility
> also is an issue.
I see backwards compatibility as the main issue here. There was a lot of
discussion preceding the inclusion of `guix shell', because of the
prospect of breaking existing tutorials/documentation floating around on
the internet. This is an even bigger concern for a more drastic
reorganisation of the CLI.
Carlo
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Guix CLI, thoughts and suggestions
2024-01-15 22:08 ` Carlo Zancanaro
@ 2024-01-20 22:50 ` Ian Eure
2024-01-22 0:21 ` Carlo Zancanaro
0 siblings, 1 reply; 8+ messages in thread
From: Ian Eure @ 2024-01-20 22:50 UTC (permalink / raw)
To: guix-devel
Hi Carlo,
Thank you for the thoughtful reply.
Carlo Zancanaro <carlo@zancanaro.id.au> writes:
> Hi Ian,
>
> Much of what you've written is fair, and I'm sure that Guix's
> commands
> could be better organised. I'm not really involved in Guix
> development,
> but I think there are two "inconsistencies" that you've
> mentioned which
> can be explained.
>
> On Mon, Jan 15 2024, Ian Eure wrote:
>> Some examples of where I think Guix could do better. This is
>> an
>> illustrative list, not an exhaustive one.
>>
>> Inconsistent organization
>> =========================
>>
>> Most package-related commands are under `guix package', but
>> many are
>> sibling commands. Examples are `guix size', `guix lint', `guix
>> hash',
>> etc.
>
> I think the real inconsistency here is that `guix package' is
> poorly
> named. This command really operates on profiles, and performs
> operations
> (install, remove, list, etc.) on those profiles. Packages are
> given as
> arguments to this command.
>
> The other commands operate on, and show the properties of,
> packages.
> Similarly with `guix build'.
>
Yes, I agree the behavior makes a bit more sense from that
viewpoint. However, it does have non-profile-related things in
it, such as `--show' and `--search'. This is getitng into another
thing I’ve seen a bit of, which is overloaded commands -- ones
that do multiple things that are unrelated or tangentally related.
But, I didn’t have a good example, and my message was long enough
already.
>> Inconsistency between verbs and options
>> =======================================
>
>> ... For example, installing a package is `guix package -i foo'
>> rather
>> than `guix package install foo', removing is `guix package -r
>> foo'
>> rather than `guix package remove foo', and listing installed
>> packages
>> is `guix package -I' rather than `guix package installed' (or
>> similar).
>
> The specific example of `guix package' might be explained by
> considering
> it as a single transaction to update the profile. The command
> `guix
> package' really says "perform a transaction on the profile", and
> the
> options are the commands in the transaction. Since there can be
> multiple
> commands, and the command names look like package names, they
> are
> provided as options.
>
> This doesn't fully explain the behaviour. In particular the
> example you
> give:
>
>> This means that users can express commands which *seem* like
>> they
>> should work, but do not. For example `guix package -i emacs -r
>> emacs-pgtk -I' represents a command to 1) install emacs 2)
>> remove
>> emacs-pgtk 3) list installed packages (which would verify the
>> previous
>> two operations occurred). ...
>
> seems reasonable to have working within the view of `guix
> package' as a
> transactional operation.
>
I agree that this would make sense, but my understanding is that
`guix package' doesn’t work like that -- it only performs the
final operation in the list. IMO, it should either do
*everything* the commands specify, or print an error and take no
action.
> It's also worth noting that there are convenience shortcuts in
> `guix
> install' and `guix remove'.
>
>> It seems like a lot of work to change, and backwards
>> compatibility
>> also is an issue.
>
> I see backwards compatibility as the main issue here. There was
> a lot of
> discussion preceding the inclusion of `guix shell', because of
> the
> prospect of breaking existing tutorials/documentation floating
> around on
> the internet. This is an even bigger concern for a more drastic
> reorganisation of the CLI.
>
I agree, I don’t think the situation can be improved without
finding a solution to preserve BC. But, I didn’t think it was
worth making detailed plans for any of this before gauging whether
the problem was one broadly considered to be worth solving.
— Ian
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Guix CLI, thoughts and suggestions
2024-01-20 22:50 ` Ian Eure
@ 2024-01-22 0:21 ` Carlo Zancanaro
2024-02-04 12:21 ` Rostislav Svoboda
0 siblings, 1 reply; 8+ messages in thread
From: Carlo Zancanaro @ 2024-01-22 0:21 UTC (permalink / raw)
To: Ian Eure; +Cc: guix-devel
Hi Ian,
On Sat, Jan 20 2024, Ian Eure wrote:
> I agree that this would make sense, but my understanding is that `guix
> package' doesn’t work like that -- it only performs the final
> operation in the list. IMO, it should either do *everything* the
> commands specify, or print an error and take no action.
It can accumulate multiple commands. As an example, if you create a
profile with a single package in it:
$ guix package -i hello
The following package will be installed:
hello 2.12.1
... more output...
then you can remove that package and install another package in a single
transaction:
$ guix package -r hello -i coreutils
The following package will be removed:
hello 2.12.1
The following package will be installed:
coreutils 9.1
... more output...
The inconsistency here is that some commands can be combined
(specifically adding and removing), whereas others cannot (probably
everything else).
> I agree, I don’t think the situation can be improved without finding a
> solution to preserve BC. But, I didn’t think it was worth making
> detailed plans for any of this before gauging whether the problem was
> one broadly considered to be worth solving.
I think it would be great to have a consistent CLI, so I would love it
if we were able to solve this problem.
Carlo
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Guix CLI, thoughts and suggestions
2024-01-22 0:21 ` Carlo Zancanaro
@ 2024-02-04 12:21 ` Rostislav Svoboda
0 siblings, 0 replies; 8+ messages in thread
From: Rostislav Svoboda @ 2024-02-04 12:21 UTC (permalink / raw)
To: guix-devel
This is something we're capable of too, right?
https://everything.curl.dev/libcurl/libcurl
Bost
Le lun. 22 janv. 2024 à 01:22, Carlo Zancanaro <carlo@zancanaro.id.au> a écrit :
>
> Hi Ian,
>
> On Sat, Jan 20 2024, Ian Eure wrote:
> > I agree that this would make sense, but my understanding is that `guix
> > package' doesn’t work like that -- it only performs the final
> > operation in the list. IMO, it should either do *everything* the
> > commands specify, or print an error and take no action.
>
> It can accumulate multiple commands. As an example, if you create a
> profile with a single package in it:
>
> $ guix package -i hello
> The following package will be installed:
> hello 2.12.1
> ... more output...
>
> then you can remove that package and install another package in a single
> transaction:
>
> $ guix package -r hello -i coreutils
> The following package will be removed:
> hello 2.12.1
>
> The following package will be installed:
> coreutils 9.1
> ... more output...
>
> The inconsistency here is that some commands can be combined
> (specifically adding and removing), whereas others cannot (probably
> everything else).
>
> > I agree, I don’t think the situation can be improved without finding a
> > solution to preserve BC. But, I didn’t think it was worth making
> > detailed plans for any of this before gauging whether the problem was
> > one broadly considered to be worth solving.
>
> I think it would be great to have a consistent CLI, so I would love it
> if we were able to solve this problem.
>
> Carlo
>
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Guix CLI, thoughts and suggestions
2024-01-15 19:24 Guix CLI, thoughts and suggestions Ian Eure
2024-01-15 21:01 ` Felix Lechner via Development of GNU Guix and the GNU System distribution.
2024-01-15 22:08 ` Carlo Zancanaro
@ 2024-01-17 7:21 ` Efraim Flashner
2024-01-18 13:51 ` Rostislav Svoboda
2 siblings, 1 reply; 8+ messages in thread
From: Efraim Flashner @ 2024-01-17 7:21 UTC (permalink / raw)
To: Ian Eure; +Cc: guix-devel
[-- Attachment #1: Type: text/plain, Size: 6933 bytes --]
On Mon, Jan 15, 2024 at 11:24:29AM -0800, Ian Eure wrote:
> Greetings,
>
> As I’ve been learning Guix, one of the things I’ve found somewhat unpleasant
> is the lack of consistency within the guix CLI tool. It feels a bit
> Git-like, with not much consistency, commands that non-obvioulsy perform
> more than operation, related commands in different places in the tree, etc.
>
> Just so you know where I’m coming from: I’ve found that compliex CLI tooling
> benefits from organization and consistency. The Linux ip(8) command is a
> good example of this kind of organization: to add an IP address, you use `ip
> address add'. To show address, `ip address show', and to remove one `ip
> address del'. When options are needed, they get added after the verb or
> branch in the verb tree; the final verb may take positional arguments as
> well as --long or -s (short)-form options.
>
> Some examples of where I think Guix could do better. This is an
> illustrative list, not an exhaustive one.
>
> Inconsistent organization
> =========================
>
> Most package-related commands are under `guix package', but many are sibling
> commands. Examples are `guix size', `guix lint', `guix hash', etc.
>
>
> Inconsistency between verbs and options
> =======================================
>
> Some verbs are bare-word positional arguments, and others are flags to
> related verbs. IMO, this is the biggest problem, and makes it very
> difficult to find all the things the CLI can do. `guix package' is a major
> offender in this area, as it mixes verbs and verb-specific options into the
> same level. For example, installing a package is `guix package -i foo'
> rather than `guix package install foo', removing is `guix package -r foo'
> rather than `guix package remove foo', and listing installed packages is
> `guix package -I' rather than `guix package installed' (or similar).
>
> This means that users can express commands which *seem* like they should
> work, but do not. For example `guix package -i emacs -r emacs-pgtk -I'
> represents a command to 1) install emacs 2) remove emacs-pgtk 3) list
> installed packages (which would verify the previous two operations
> occurred). This is a valid command within the accepted organization of
> `guix package', and doesn’t cause an error, but doesn’t work: the install
> and remove steps are ignored.
I found this part surprising. I know you can chain together -i and -r,
but I had never tried adding -I to the list also, and it makes sense to
me that it should be able to be chained in also.
> A thing I’ve found throughout my career is
> that designing systems so it’s *impossible* to represent unsupported,
> nonsensical, or undefined things is an extremely valuable technique to avoid
> errors and pitfalls. I think Guix could get a lot of mileage out of
> adopting something similar.
>
> This causes a related problem of making it impossible to know what options
> are valid for what verbs. Will `guix package --cores=8 -r emacs' remove the
> package while using eight cores of my system? Will `guix system -s i686
> switch-generation 5' switch me to a 32-bit version of generation 5? If
> verbs are organized better, and have their own options, this ambiguity
> vanishes.
>
>
> More inconsistency
> ==================
>
> Other parts of guix have the opposite problem: `guix system docker-image'
> probably ought to be an option to `guix system image' rather than a separate
> verb.
>
>
> Inconsistency between similar commands
> ======================================
>
> There are generations of both the system (for GuixSD) and the user profile,
> however, they work differently. For the system, there’s `guix system
> list-generations' and `guix system switch-generation', but for the user
> profile, you need `guix package --list-generations' and `guix package
> --switch-generation=PATTERN'. Additionally, no help is available for either
> of the system commands: `guix system switch-generations --help' gives the
> same output as `guix system --help' -- no description of the supported ways
> of expressing a generation are available.
>
>
> Flattened verbs
> ===============
>
> Related, the generation-related commands under `guix system' ought to be one
> level deeper: `guix system generation list', `guix system generation switch'
> etc.
>
>
> Repeated options
> ================
>
> Many commands (`guix package', `guix system', `guix build', `guix shell')
> take -L options, to add Guile source to their load-path. This probably ought
> to be an option to guix itself, so you can do `guix -L~/src/my-channel build
> ...'.
>
>
> Suggestions
> ===========
>
> All commands should be organized into a tree of verbs.
>
> Verbs should have common aliases (`rm' for `remove', etc).
>
> Verbs should be selected by specifying the minimum unambiguous substring.
> For example `guix sys gen sw' could refer to `guix system generation
> switch'.
>
> Options should be applicable to each level of the tree, ex `guix
> -L~/src/my-channel' would add that load-path, which would be visible to any
> command.
>
> Requesting help is a verb. Appending "help" to any level of the verb tree
> should show both options applicable to that verb, and its child verbs.
> `guix help' would show global options and all top-level verbs (package,
> system, generation, etc); `guix package help' would show package-specific
> options and package-specific verbs; and so on.
>
>
> Conclusion
> ==========
>
> I have no idea if anyone feels similarly about this, or whether there’s
> appetite to change the CLI, but I think it’d be time well-spent. Having
> some kind of agreed-upon standard for how the CLI stuff is organized seems
> like a good thing to me, even if it just stops or slows the addition of more
> commands with unique expressions.
>
> It seems like a lot of work to change, and backwards compatibility also is
> an issue. One option I could see working is shoving the entire existing
> structure under a command in the new tool, so you could do `guix old package
> -I' or similar. An alternate approach would be using an environment
> variable to change behaviors.
>
> What do you all think?
This is probably the most well written critique I've seen on the layout
of the CLI for Guix.
I think it would be worthwhile to mock-up a 'guix profile' command to
see how it would look. I'm going to add it as a possible topic for Guix
Days just before FOSDEM and see if we can create something that makes
more sense.
--
Efraim Flashner <efraim@flashner.co.il> רנשלפ םירפא
GPG key = A28B F40C 3E55 1372 662D 14F7 41AA E7DC CA3D 8351
Confidentiality cannot be guaranteed on emails sent or received unencrypted
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Guix CLI, thoughts and suggestions
2024-01-17 7:21 ` Efraim Flashner
@ 2024-01-18 13:51 ` Rostislav Svoboda
0 siblings, 0 replies; 8+ messages in thread
From: Rostislav Svoboda @ 2024-01-18 13:51 UTC (permalink / raw)
To: Ian Eure, guix-devel
I find the discrepancy regarding two dashes '--' is annoying:
$ guix package --list-generations=1d
...
$ guix describe --list-generations=1d
guix system: error: list-generations=1d: unrecognized option
$ guix describe list-generations=1d
...
And more importantly, I'd be happy if the CLI and REPL syntax were
united, so that there's minimal difference between a shell command
call and a Guile function call. E.g. following would do the same:
$ guix :show emacs
scheme@(guix-user)> (guix :show emacs)
This would greatly facilitate the shell-to-Guile script conversion.
(This way, for comp-sci newcomers, it's much easier to see what a
(bash) shell, with its quirky DSL, really is - not an interface making
computers easier to use, but a barrier obstructing you from properly
using computers as programmable stateful machines. See
https://www.gnu.org/software/guile/manual/html_node/Prompts.html )
Unfortunately, the '#' indicates a comment-start in shells and, as
AFAICS in the source code, we prefer the #:keyword syntax over
:keyword. (Here, in the first step, on an experimental branch, we
could try to add (read-set! keywords 'prefix) everywhere, just to see
what breaks ;-)
Cheers Bost
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2024-02-04 12:22 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-01-15 19:24 Guix CLI, thoughts and suggestions Ian Eure
2024-01-15 21:01 ` Felix Lechner via Development of GNU Guix and the GNU System distribution.
2024-01-15 22:08 ` Carlo Zancanaro
2024-01-20 22:50 ` Ian Eure
2024-01-22 0:21 ` Carlo Zancanaro
2024-02-04 12:21 ` Rostislav Svoboda
2024-01-17 7:21 ` Efraim Flashner
2024-01-18 13:51 ` Rostislav Svoboda
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/guix.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).