From debbugs-submit-bounces@debbugs.gnu.org Tue Sep 01 16:35:36 2020 Received: (at submit) by debbugs.gnu.org; 1 Sep 2020 20:35:36 +0000 Received: from localhost ([127.0.0.1]:57462 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDD0C-0002Xj-3r for submit@debbugs.gnu.org; Tue, 01 Sep 2020 16:35:36 -0400 Received: from lists.gnu.org ([209.51.188.17]:44342) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDD0A-0002Xc-H2 for submit@debbugs.gnu.org; Tue, 01 Sep 2020 16:35:35 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:45452) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kDD0A-0002tz-A1 for guix-patches@gnu.org; Tue, 01 Sep 2020 16:35:34 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:58738) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kDD09-0005jB-7a; Tue, 01 Sep 2020 16:35:33 -0400 Received: from [2a01:e0a:1d:7270:af76:b9b:ca24:c465] (port=51538 helo=gnu.org) by fencepost.gnu.org with esmtpsa (TLS1.2:DHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kDD08-0007Rd-LS; Tue, 01 Sep 2020 16:35:33 -0400 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= To: guix-patches@gnu.org Subject: [PATCH 0/2] Make 'guix help' helpful Date: Tue, 1 Sep 2020 22:35:20 +0200 Message-Id: <20200901203520.21103-1-ludo@gnu.org> X-Mailer: git-send-email 2.28.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: submit Cc: =?UTF-8?q?Ludovic=20Court=C3=A8s?= X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Hey Guix! Here’s another long-overdue change that was brought to my attention: making ‘guix help’ show a synopsis of each command. While at it, it also groups them in categories (I more or less followed the manual, but there’s prolly room for improvement, like a ‘packaging’ category maybe?): --8<---------------cut here---------------start------------->8--- $ ./pre-inst-env guix help Usage: guix COMMAND ARGS... Run COMMAND with ARGS. COMMAND must be one of the sub-commands listed below: main commands: deploy deploy operating systems on a set of machines describe describe the channel revisions currently used gc invoke the garbage collector install install packages package manage packages and profiles pull pull the latest revision of Guix remove removed installed packages search search for packages show show information about packages system build and deploy full operating systems time-machine run commands from a different revision upgrade upgrade packages to their latest version weather report on the available of pre-built package binaries commands for developers: build build packages or derivations without installing them container run code in containers created by 'guix environment -C' edit view and edit package definitions environment spawn one-off software environments import import a package definition from an external repository pack create application bundles refresh update existing package definitions advanced usage: archive manipulate, export, and import normalized archives (nars) challenge challenge substitute servers, comparing their binaries copy copy store items remotely over SSH download download a file to the store and print its hash git operate on Git repositories graph view and query package dependency graphs hash compute the cryptographic hash of a file lint validate package definitions offload set up and operate build offloading processes list currently running sessions publish publish build results over HTTP repl read-eval-print loop (REPL) for interactive programming size profile the on-disk size of packages Report bugs to: bug-guix@gnu.org. GNU Guix home page: General help using Guix and GNU software: --8<---------------cut here---------------end--------------->8--- Much more… helpful than what we currently have, no? :-) This works by introducing a new ‘define-command’ macro that each command now uses and where it defines its synopsis. ‘guix help’ actually reads files in search of ‘define-command’, which is cheaper than loading each module and doing some sort of introspection. The URL shown at the end (“General help”) is also changed, as was rightfully suggested by zimoun a while back. Thoughts? Ludo’. PS: We can talk about categories, but make sure to turn on the bikeshedding limitation mode of your mail client. :-) Ludovic Courtès (2): scripts: Use 'define-command' and have 'guix help' use that. ui: '--help' output links to . guix/scripts.scm | 29 ++++++++++- guix/scripts/archive.scm | 5 +- guix/scripts/authenticate.scm | 8 ++- guix/scripts/build.scm | 5 +- guix/scripts/challenge.scm | 5 +- guix/scripts/container.scm | 6 ++- guix/scripts/copy.scm | 5 +- guix/scripts/deploy.scm | 3 +- guix/scripts/describe.scm | 3 +- guix/scripts/download.scm | 5 +- guix/scripts/edit.scm | 7 ++- guix/scripts/environment.scm | 5 +- guix/scripts/gc.scm | 4 +- guix/scripts/git.scm | 6 ++- guix/scripts/graph.scm | 5 +- guix/scripts/hash.scm | 5 +- guix/scripts/import.scm | 8 ++- guix/scripts/install.scm | 6 ++- guix/scripts/lint.scm | 5 +- guix/scripts/offload.scm | 6 ++- guix/scripts/pack.scm | 5 +- guix/scripts/package.scm | 4 +- guix/scripts/perform-download.scm | 18 ++++--- guix/scripts/processes.scm | 4 +- guix/scripts/publish.scm | 5 +- guix/scripts/pull.scm | 4 +- guix/scripts/refresh.scm | 7 ++- guix/scripts/remove.scm | 6 ++- guix/scripts/repl.scm | 5 +- guix/scripts/search.scm | 6 ++- guix/scripts/show.scm | 4 +- guix/scripts/size.scm | 7 ++- guix/scripts/substitute.scm | 7 ++- guix/scripts/system.scm | 4 +- guix/scripts/time-machine.scm | 4 +- guix/scripts/upgrade.scm | 6 ++- guix/scripts/weather.scm | 4 +- guix/ui.scm | 82 +++++++++++++++++++++++++++---- 38 files changed, 249 insertions(+), 64 deletions(-) -- 2.28.0 From debbugs-submit-bounces@debbugs.gnu.org Tue Sep 01 16:41:55 2020 Received: (at 43159) by debbugs.gnu.org; 1 Sep 2020 20:41:55 +0000 Received: from localhost ([127.0.0.1]:57473 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDD6J-0002hK-AU for submit@debbugs.gnu.org; Tue, 01 Sep 2020 16:41:55 -0400 Received: from eggs.gnu.org ([209.51.188.92]:36468) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDD6I-0002h3-9X for 43159@debbugs.gnu.org; Tue, 01 Sep 2020 16:41:54 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:58807) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kDD6C-0006Q0-LV; Tue, 01 Sep 2020 16:41:48 -0400 Received: from [2a01:e0a:1d:7270:af76:b9b:ca24:c465] (port=51614 helo=gnu.org) by fencepost.gnu.org with esmtpsa (TLS1.2:DHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kDD6C-0007qm-5z; Tue, 01 Sep 2020 16:41:48 -0400 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= To: 43159@debbugs.gnu.org Subject: [PATCH 2/2] ui: '--help' output links to . Date: Tue, 1 Sep 2020 22:41:36 +0200 Message-Id: <20200901204136.21375-2-ludo@gnu.org> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20200901204136.21375-1-ludo@gnu.org> References: <20200901204136.21375-1-ludo@gnu.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 43159 Cc: =?UTF-8?q?Ludovic=20Court=C3=A8s?= X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) * guix/ui.scm (show-bug-report-information): Link to instead of . The former is much more useful and includes links to GNU manuals. --- guix/ui.scm | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/guix/ui.scm b/guix/ui.scm index 4d90a47bb9..87a1925a4b 100644 --- a/guix/ui.scm +++ b/guix/ui.scm @@ -542,8 +542,9 @@ There is NO WARRANTY, to the extent permitted by law. Report bugs to: ~a.") %guix-bug-report-address) (format #t (G_ " ~a home page: <~a>") %guix-package-name %guix-home-page-url) - (display (G_ " -General help using GNU software: ")) + (format #t (G_ " +General help using Guix and GNU software: <~a>") + "https://guix.gnu.org/help/") (newline)) (define (augmented-system-error-handler file) -- 2.28.0 From debbugs-submit-bounces@debbugs.gnu.org Tue Sep 01 16:42:02 2020 Received: (at 43159) by debbugs.gnu.org; 1 Sep 2020 20:42:02 +0000 Received: from localhost ([127.0.0.1]:57475 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDD6J-0002hM-JH for submit@debbugs.gnu.org; Tue, 01 Sep 2020 16:42:02 -0400 Received: from eggs.gnu.org ([209.51.188.92]:36456) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDD6H-0002h0-4t for 43159@debbugs.gnu.org; Tue, 01 Sep 2020 16:41:54 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:58806) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kDD6B-0006Ps-Ri; Tue, 01 Sep 2020 16:41:47 -0400 Received: from [2a01:e0a:1d:7270:af76:b9b:ca24:c465] (port=51614 helo=gnu.org) by fencepost.gnu.org with esmtpsa (TLS1.2:DHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kDD6A-0007qm-FB; Tue, 01 Sep 2020 16:41:47 -0400 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= To: 43159@debbugs.gnu.org Subject: [PATCH 1/2] scripts: Use 'define-command' and have 'guix help' use that. Date: Tue, 1 Sep 2020 22:41:35 +0200 Message-Id: <20200901204136.21375-1-ludo@gnu.org> X-Mailer: git-send-email 2.28.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 43159 Cc: =?UTF-8?q?Ludovic=20Court=C3=A8s?= X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) This changes 'guix help' to print a short synopsis for each command and to group commands by category. * guix/scripts.scm (synopsis, category): New variables. (define-command): New macro. * guix/ui.scm (): New record type. (source-file-command): New procedure. (command-files): Return absolute file names. (commands): Return a list of records. (show-guix-help)[display-commands, category-predicate]: New procedures. Display commands grouped in three categories. * guix/scripts/archive.scm (guix-archive): Use 'define-command'. * guix/scripts/authenticate.scm (guix-authenticate): Likewise. * guix/scripts/build.scm (guix-build): Likewise. * guix/scripts/challenge.scm (guix-challenge): Likewise. * guix/scripts/container.scm (guix-container): Likewise. * guix/scripts/copy.scm (guix-copy): Likewise. * guix/scripts/deploy.scm (guix-deploy): Likewise. * guix/scripts/describe.scm (guix-describe): Likewise. * guix/scripts/download.scm (guix-download): Likewise. * guix/scripts/edit.scm (guix-edit): Likewise. * guix/scripts/environment.scm (guix-environment): Likewise. * guix/scripts/gc.scm (guix-gc): Likewise. * guix/scripts/git.scm (guix-git): Likewise. * guix/scripts/graph.scm (guix-graph): Likewise. * guix/scripts/hash.scm (guix-hash): Likewise. * guix/scripts/import.scm (guix-import): Likewise. * guix/scripts/install.scm (guix-install): Likewise. * guix/scripts/lint.scm (guix-lint): Likewise. * guix/scripts/offload.scm (guix-offload): Likewise. * guix/scripts/pack.scm (guix-pack): Likewise. * guix/scripts/package.scm (guix-package): Likewise. * guix/scripts/perform-download.scm (guix-perform-download): Likewise. * guix/scripts/processes.scm (guix-processes): Likewise. * guix/scripts/publish.scm (guix-publish): Likewise. * guix/scripts/pull.scm (guix-pull): Likewise. * guix/scripts/refresh.scm (guix-refresh): Likewise. * guix/scripts/remove.scm (guix-remove): Likewise. * guix/scripts/repl.scm (guix-repl): Likewise. * guix/scripts/search.scm (guix-search): Likewise. * guix/scripts/show.scm (guix-show): Likewise. * guix/scripts/size.scm (guix-size): Likewise. * guix/scripts/substitute.scm (guix-substitute): Likewise. * guix/scripts/system.scm (guix-system): Likewise. * guix/scripts/time-machine.scm (guix-time-machine): Likewise. * guix/scripts/upgrade.scm (guix-upgrade): Likewise. * guix/scripts/weather.scm (guix-weather): Likewise. --- guix/scripts.scm | 29 +++++++++++- guix/scripts/archive.scm | 5 +- guix/scripts/authenticate.scm | 8 +++- guix/scripts/build.scm | 5 +- guix/scripts/challenge.scm | 5 +- guix/scripts/container.scm | 6 ++- guix/scripts/copy.scm | 5 +- guix/scripts/deploy.scm | 3 +- guix/scripts/describe.scm | 3 +- guix/scripts/download.scm | 5 +- guix/scripts/edit.scm | 7 ++- guix/scripts/environment.scm | 5 +- guix/scripts/gc.scm | 4 +- guix/scripts/git.scm | 6 ++- guix/scripts/graph.scm | 5 +- guix/scripts/hash.scm | 5 +- guix/scripts/import.scm | 8 +++- guix/scripts/install.scm | 6 ++- guix/scripts/lint.scm | 5 +- guix/scripts/offload.scm | 6 ++- guix/scripts/pack.scm | 5 +- guix/scripts/package.scm | 4 +- guix/scripts/perform-download.scm | 18 ++++---- guix/scripts/processes.scm | 4 +- guix/scripts/publish.scm | 5 +- guix/scripts/pull.scm | 4 +- guix/scripts/refresh.scm | 7 ++- guix/scripts/remove.scm | 6 ++- guix/scripts/repl.scm | 5 +- guix/scripts/search.scm | 6 ++- guix/scripts/show.scm | 4 +- guix/scripts/size.scm | 7 ++- guix/scripts/substitute.scm | 7 ++- guix/scripts/system.scm | 4 +- guix/scripts/time-machine.scm | 4 +- guix/scripts/upgrade.scm | 6 ++- guix/scripts/weather.scm | 4 +- guix/ui.scm | 77 +++++++++++++++++++++++++++---- 38 files changed, 246 insertions(+), 62 deletions(-) diff --git a/guix/scripts.scm b/guix/scripts.scm index 8534948892..013b775818 100644 --- a/guix/scripts.scm +++ b/guix/scripts.scm @@ -34,7 +34,10 @@ #:use-module (srfi srfi-19) #:use-module (srfi srfi-37) #:use-module (ice-9 match) - #:export (args-fold* + #:export (synopsis + category + define-command + args-fold* parse-command-line maybe-build build-package @@ -50,6 +53,30 @@ ;;; ;;; Code: +;; Syntactic keywords. +(define synopsis 'command-synopsis) +(define category 'command-category) + +(define-syntax define-command + (syntax-rules (category synopsis) + "Define the given command as a procedure along with its synopsis and, +optionally, its category. The synopsis becomes the docstring of the +procedure, but both the category and synopsis are meant to be read (parsed) by +'guix help'." + ;; The (synopsis ...) form is here so that xgettext sees those strings as + ;; translatable. + ((_ (name . args) + (synopsis doc) body ...) + (define (name . args) + doc + body ...)) + ((_ (name . args) + (category _) + (synopsis doc) body ...) + (define (name . args) + doc + body ...)))) + (define (args-fold* args options unrecognized-option-proc operand-proc . seeds) "A wrapper on top of `args-fold' that does proper user-facing error reporting." diff --git a/guix/scripts/archive.scm b/guix/scripts/archive.scm index f3b86fba14..8796774a01 100644 --- a/guix/scripts/archive.scm +++ b/guix/scripts/archive.scm @@ -355,7 +355,10 @@ output port." ;;; Entry point. ;;; -(define (guix-archive . args) +(define-command (guix-archive . args) + (category advanced) + (synopsis "manipulate, export, and import normalized archives (nars)") + (define (lines port) ;; Return lines read from PORT. (let loop ((line (read-line port)) diff --git a/guix/scripts/authenticate.scm b/guix/scripts/authenticate.scm index f1fd8ee895..a4b9171fc7 100644 --- a/guix/scripts/authenticate.scm +++ b/guix/scripts/authenticate.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2013, 2014, 2015, 2016, 2017 Ludovic Courtès +;;; Copyright © 2013, 2014, 2015, 2016, 2017, 2020 Ludovic Courtès ;;; ;;; This file is part of GNU Guix. ;;; @@ -18,6 +18,7 @@ (define-module (guix scripts authenticate) #:use-module (guix config) + #:use-module (guix scripts) #:use-module (guix base16) #:use-module (gcrypt pk-crypto) #:use-module (guix pki) @@ -90,7 +91,10 @@ to stdout upon success." ;;; unmodified currently. ;;; -(define (guix-authenticate . args) +(define-command (guix-authenticate . args) + (category internal) + (synopsis "sign or verify signatures on normalized archives (nars)") + ;; Signature sexps written to stdout may contain binary data, so force ;; ISO-8859-1 encoding so that things are not mangled. See ;; for details. diff --git a/guix/scripts/build.scm b/guix/scripts/build.scm index 6286a43c02..37b8d82fd5 100644 --- a/guix/scripts/build.scm +++ b/guix/scripts/build.scm @@ -945,7 +945,10 @@ needed." ;;; Entry point. ;;; -(define (guix-build . args) +(define-command (guix-build . args) + (category development) + (synopsis "build packages or derivations without installing them") + (define opts (parse-command-line args %options (list %default-options))) diff --git a/guix/scripts/challenge.scm b/guix/scripts/challenge.scm index 624f51b200..6aab53152e 100644 --- a/guix/scripts/challenge.scm +++ b/guix/scripts/challenge.scm @@ -475,7 +475,10 @@ Challenge the substitutes for PACKAGE... provided by one or more servers.\n")) ;;; Entry point. ;;; -(define (guix-challenge . args) +(define-command (guix-challenge . args) + (category advanced) + (synopsis "challenge substitute servers, comparing their binaries") + (with-error-handling (let* ((opts (parse-command-line args %options (list %default-options) #:build-options? #f)) diff --git a/guix/scripts/container.scm b/guix/scripts/container.scm index 8041d64b6b..2369437043 100644 --- a/guix/scripts/container.scm +++ b/guix/scripts/container.scm @@ -20,6 +20,7 @@ (define-module (guix scripts container) #:use-module (ice-9 match) #:use-module (guix ui) + #:use-module (guix scripts) #:export (guix-container)) (define (show-help) @@ -46,7 +47,10 @@ Build and manipulate Linux containers.\n")) (proc (string->symbol (string-append "guix-container-" name)))) (module-ref module proc))) -(define (guix-container . args) +(define-command (guix-container . args) + (category development) + (synopsis "run code in containers created by 'guix environment -C'") + (with-error-handling (match args (() diff --git a/guix/scripts/copy.scm b/guix/scripts/copy.scm index 274620fc1e..b2eccae7a6 100644 --- a/guix/scripts/copy.scm +++ b/guix/scripts/copy.scm @@ -170,7 +170,10 @@ Copy ITEMS to or from the specified host over SSH.\n")) ;;; Entry point. ;;; -(define (guix-copy . args) +(define-command (guix-copy . args) + (category advanced) + (synopsis "copy store items remotely over SSH") + (with-error-handling (let* ((opts (parse-command-line args %options (list %default-options))) (source (assoc-ref opts 'source)) diff --git a/guix/scripts/deploy.scm b/guix/scripts/deploy.scm index 4a68197620..1b5be307be 100644 --- a/guix/scripts/deploy.scm +++ b/guix/scripts/deploy.scm @@ -136,7 +136,8 @@ Perform the deployment specified by FILE.\n")) (machine-display-name machine)))) -(define (guix-deploy . args) +(define-command (guix-deploy . args) + (synopsis "deploy operating systems on a set of machines") (define (handle-argument arg result) (alist-cons 'file arg result)) diff --git a/guix/scripts/describe.scm b/guix/scripts/describe.scm index bc868ffbbf..c3667516eb 100644 --- a/guix/scripts/describe.scm +++ b/guix/scripts/describe.scm @@ -304,7 +304,8 @@ text. The hyperlink links to a web view of COMMIT, when available." ;;; Entry point. ;;; -(define (guix-describe . args) +(define-command (guix-describe . args) + (synopsis "describe the channel revisions currently used") (let* ((opts (args-fold* args %options (lambda (opt name arg result) (leave (G_ "~A: unrecognized option~%") diff --git a/guix/scripts/download.scm b/guix/scripts/download.scm index 589f62da9d..7192aa14d0 100644 --- a/guix/scripts/download.scm +++ b/guix/scripts/download.scm @@ -156,7 +156,10 @@ and 'base16' ('hex' and 'hexadecimal' can be used as well).\n")) ;;; Entry point. ;;; -(define (guix-download . args) +(define-command (guix-download . args) + (category advanced) + (synopsis "download a file to the store and print its hash") + (define (parse-options) ;; Return the alist of option values. (args-fold* args %options diff --git a/guix/scripts/edit.scm b/guix/scripts/edit.scm index 43f3011869..39bd4f8a6c 100644 --- a/guix/scripts/edit.scm +++ b/guix/scripts/edit.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2015, 2016, 2019 Ludovic Courtès +;;; Copyright © 2015, 2016, 2019, 2020 Ludovic Courtès ;;; Copyright © 2015 Mathieu Lirzin ;;; Copyright © 2020 Simon Tournier ;;; @@ -78,7 +78,10 @@ line." (search-path* %load-path (location-file location)))) -(define (guix-edit . args) +(define-command (guix-edit . args) + (category development) + (synopsis "view and edit package definitions") + (define (parse-arguments) ;; Return the list of package names. (args-fold* args %options diff --git a/guix/scripts/environment.scm b/guix/scripts/environment.scm index 1fb3505307..ad50281eb2 100644 --- a/guix/scripts/environment.scm +++ b/guix/scripts/environment.scm @@ -678,7 +678,10 @@ message if any test fails." ;;; Entry point. ;;; -(define (guix-environment . args) +(define-command (guix-environment . args) + (category development) + (synopsis "spawn one-off software environments") + (with-error-handling (let* ((opts (parse-args args)) (pure? (assoc-ref opts 'pure)) diff --git a/guix/scripts/gc.scm b/guix/scripts/gc.scm index ab7c13315f..043273f491 100644 --- a/guix/scripts/gc.scm +++ b/guix/scripts/gc.scm @@ -220,7 +220,9 @@ is deprecated; use '-D'~%")) ;;; Entry point. ;;; -(define (guix-gc . args) +(define-command (guix-gc . args) + (synopsis "invoke the garbage collector") + (define (parse-options) ;; Return the alist of option values. (parse-command-line args %options (list %default-options) diff --git a/guix/scripts/git.scm b/guix/scripts/git.scm index bc829cbe99..58a496a1b2 100644 --- a/guix/scripts/git.scm +++ b/guix/scripts/git.scm @@ -19,6 +19,7 @@ (define-module (guix scripts git) #:use-module (ice-9 match) #:use-module (guix ui) + #:use-module (guix scripts) #:export (guix-git)) (define (show-help) @@ -45,7 +46,10 @@ Operate on Git repositories.\n")) (proc (string->symbol (string-append "guix-git-" name)))) (module-ref module proc))) -(define (guix-git . args) +(define-command (guix-git . args) + (category advanced) + (synopsis "operate on Git repositories") + (with-error-handling (match args (() diff --git a/guix/scripts/graph.scm b/guix/scripts/graph.scm index 73d9269de2..bfeda4f61b 100644 --- a/guix/scripts/graph.scm +++ b/guix/scripts/graph.scm @@ -565,7 +565,10 @@ Emit a representation of the dependency graph of PACKAGE...\n")) ;;; Entry point. ;;; -(define (guix-graph . args) +(define-command (guix-graph . args) + (category advanced) + (synopsis "view and query package dependency graphs") + (with-error-handling (define opts (parse-command-line args %options diff --git a/guix/scripts/hash.scm b/guix/scripts/hash.scm index 9b4f419a24..480814df20 100644 --- a/guix/scripts/hash.scm +++ b/guix/scripts/hash.scm @@ -116,7 +116,10 @@ and 'base16' ('hex' and 'hexadecimal' can be used as well).\n")) ;;; Entry point. ;;; -(define (guix-hash . args) +(define-command (guix-hash . args) + (category advanced) + (synopsis "compute the cryptographic hash of a file") + (define (parse-options) ;; Return the alist of option values. (parse-command-line args %options (list %default-options) diff --git a/guix/scripts/import.scm b/guix/scripts/import.scm index c6cc93fad8..6e972561fb 100644 --- a/guix/scripts/import.scm +++ b/guix/scripts/import.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2012, 2013, 2014 Ludovic Courtès +;;; Copyright © 2012, 2013, 2014, 2020 Ludovic Courtès ;;; Copyright © 2014 David Thompson ;;; Copyright © 2018 Kyle Meyer ;;; Copyright © 2019 Ricardo Wurmus @@ -21,6 +21,7 @@ (define-module (guix scripts import) #:use-module (guix ui) + #:use-module (guix scripts) #:use-module (guix utils) #:use-module (srfi srfi-1) #:use-module (srfi srfi-11) @@ -98,7 +99,10 @@ Run IMPORTER with ARGS.\n")) (newline) (show-bug-report-information)) -(define (guix-import . args) +(define-command (guix-import . args) + (category development) + (synopsis "import a package definition from an external repository") + (match args (() (format (current-error-port) diff --git a/guix/scripts/install.scm b/guix/scripts/install.scm index d88e86e77a..894e60f9da 100644 --- a/guix/scripts/install.scm +++ b/guix/scripts/install.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2019 Ludovic Courtès +;;; Copyright © 2019, 2020 Ludovic Courtès ;;; ;;; This file is part of GNU Guix. ;;; @@ -66,7 +66,9 @@ This is an alias for 'guix package -i'.\n")) %transformation-options %standard-build-options))) -(define (guix-install . args) +(define-command (guix-install . args) + (synopsis "install packages") + (define (handle-argument arg result arg-handler) ;; Treat all non-option arguments as package specs. (values (alist-cons 'install arg result) diff --git a/guix/scripts/lint.scm b/guix/scripts/lint.scm index 5168a1ca17..76bf18220a 100644 --- a/guix/scripts/lint.scm +++ b/guix/scripts/lint.scm @@ -157,7 +157,10 @@ run the checkers on all packages.\n")) ;;; Entry Point ;;; -(define (guix-lint . args) +(define-command (guix-lint . args) + (category advanced) + (synopsis "validate package definitions") + (define (parse-options) ;; Return the alist of option values. (parse-command-line args %options (list %default-options) diff --git a/guix/scripts/offload.scm b/guix/scripts/offload.scm index 1e0e9d7905..4afdb9396d 100644 --- a/guix/scripts/offload.scm +++ b/guix/scripts/offload.scm @@ -39,6 +39,7 @@ #:select (fcntl-flock set-thread-name)) #:use-module ((guix build utils) #:select (which mkdir-p)) #:use-module (guix ui) + #:use-module (guix scripts) #:use-module (guix diagnostics) #:use-module (srfi srfi-1) #:use-module (srfi srfi-11) @@ -725,7 +726,10 @@ machine." ;;; Entry point. ;;; -(define (guix-offload . args) +(define-command (guix-offload . args) + (category advanced) + (synopsis "set up and operate build offloading") + (define request-line-rx ;; The request format. See 'tryBuildHook' method in build.cc. (make-regexp "([01]) ([a-z0-9_-]+) (/[[:graph:]]+.drv) ([[:graph:]]*)")) diff --git a/guix/scripts/pack.scm b/guix/scripts/pack.scm index 9d6881fdaf..379e6a3ac6 100644 --- a/guix/scripts/pack.scm +++ b/guix/scripts/pack.scm @@ -1089,7 +1089,10 @@ Create a bundle of PACKAGE.\n")) ;;; Entry point. ;;; -(define (guix-pack . args) +(define-command (guix-pack . args) + (category development) + (synopsis "create application bundles") + (define opts (parse-command-line args %options (list %default-options))) diff --git a/guix/scripts/package.scm b/guix/scripts/package.scm index ac8dedb5f3..4eb968a49b 100644 --- a/guix/scripts/package.scm +++ b/guix/scripts/package.scm @@ -941,7 +941,9 @@ processed, #f otherwise." ;;; Entry point. ;;; -(define (guix-package . args) +(define-command (guix-package . args) + (synopsis "manage packages and profiles") + (define (handle-argument arg result arg-handler) ;; Process non-option argument ARG by calling back ARG-HANDLER. (if arg-handler diff --git a/guix/scripts/perform-download.scm b/guix/scripts/perform-download.scm index df787a9940..8d409092ba 100644 --- a/guix/scripts/perform-download.scm +++ b/guix/scripts/perform-download.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2016, 2017, 2018 Ludovic Courtès +;;; Copyright © 2016, 2017, 2018, 2020 Ludovic Courtès ;;; ;;; This file is part of GNU Guix. ;;; @@ -18,6 +18,7 @@ (define-module (guix scripts perform-download) #:use-module (guix ui) + #:use-module (guix scripts) #:use-module (guix derivations) #:use-module ((guix store) #:select (derivation-path? store-path?)) #:use-module (guix build download) @@ -91,14 +92,15 @@ actual output is different from that when we're doing a 'bmCheck' or (leave (G_ "refusing to run with elevated privileges (UID ~a)~%") (getuid)))) -(define (guix-perform-download . args) - "Perform the download described by the given fixed-output derivation. +(define-command (guix-perform-download . args) + (category internal) + (synopsis "perform download described by fixed-output derivations") -This is an \"out-of-band\" download in that this code is executed directly by -the daemon and not explicitly described as an input of the derivation. This -allows us to sidestep bootstrapping problems, such downloading the source code -of GnuTLS over HTTPS, before we have built GnuTLS. See -." + ;; This is an "out-of-band" download in that this code is executed directly + ;; by the daemon and not explicitly described as an input of the derivation. + ;; This allows us to sidestep bootstrapping problems, such as downloading + ;; the source code of GnuTLS over HTTPS before we have built GnuTLS. See + ;; . (define print-build-trace? (match (getenv "_NIX_OPTIONS") diff --git a/guix/scripts/processes.scm b/guix/scripts/processes.scm index 35698a0216..272eae2f6f 100644 --- a/guix/scripts/processes.scm +++ b/guix/scripts/processes.scm @@ -223,7 +223,9 @@ List the current Guix sessions and their processes.")) ;;; Entry point. ;;; -(define (guix-processes . args) +(define-command (guix-processes . args) + (category advanced) + (synopsis "list currently running sessions") (define options (args-fold* args %options (lambda (opt name arg result) diff --git a/guix/scripts/publish.scm b/guix/scripts/publish.scm index 61542f83a0..872931840a 100644 --- a/guix/scripts/publish.scm +++ b/guix/scripts/publish.scm @@ -1013,7 +1013,10 @@ methods, return the applicable compression." ;;; Entry point. ;;; -(define (guix-publish . args) +(define-command (guix-publish . args) + (category advanced) + (synopsis "publish build results over HTTP") + (with-error-handling (let* ((opts (args-fold* args %options (lambda (opt name arg result) diff --git a/guix/scripts/pull.scm b/guix/scripts/pull.scm index 3b980b8f3f..bb1b560a22 100644 --- a/guix/scripts/pull.scm +++ b/guix/scripts/pull.scm @@ -751,7 +751,9 @@ Use '~/.config/guix/channels.scm' instead.")) channels))) -(define (guix-pull . args) +(define-command (guix-pull . args) + (synopsis "pull the latest revision of Guix") + (with-error-handling (with-git-error-handling (let* ((opts (parse-command-line args %options diff --git a/guix/scripts/refresh.scm b/guix/scripts/refresh.scm index efada1df5a..eba996d6c6 100644 --- a/guix/scripts/refresh.scm +++ b/guix/scripts/refresh.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2013, 2014, 2015, 2016, 2017, 2018, 2019 Ludovic Courtès +;;; Copyright © 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 Ludovic Courtès ;;; Copyright © 2013 Nikita Karetnikov ;;; Copyright © 2014 Eric Bavier ;;; Copyright © 2015 Alex Kost @@ -496,7 +496,10 @@ all are dependent packages: ~{~a~^ ~}~%") ;;; Entry point. ;;; -(define (guix-refresh . args) +(define-command (guix-refresh . args) + (category development) + (synopsis "update existing package definitions") + (define (parse-options) ;; Return the alist of option values. (parse-command-line args %options (list %default-options) diff --git a/guix/scripts/remove.scm b/guix/scripts/remove.scm index 2f06ea4f37..e05fb05f07 100644 --- a/guix/scripts/remove.scm +++ b/guix/scripts/remove.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2019 Ludovic Courtès +;;; Copyright © 2019, 2020 Ludovic Courtès ;;; ;;; This file is part of GNU Guix. ;;; @@ -63,7 +63,9 @@ This is an alias for 'guix package -r'.\n")) %standard-build-options))) -(define (guix-remove . args) +(define-command (guix-remove . args) + (synopsis "removed installed packages") + (define (handle-argument arg result arg-handler) ;; Treat all non-option arguments as package specs. (values (alist-cons 'remove arg result) diff --git a/guix/scripts/repl.scm b/guix/scripts/repl.scm index 0ea9c3655c..202a3a197f 100644 --- a/guix/scripts/repl.scm +++ b/guix/scripts/repl.scm @@ -137,7 +137,10 @@ call THUNK." (loop))))))) -(define (guix-repl . args) +(define-command (guix-repl . args) + (category advanced) + (synopsis "read-eval-print loop (REPL) for interactive programming") + (define opts (args-fold* args %options (lambda (opt name arg result) diff --git a/guix/scripts/search.scm b/guix/scripts/search.scm index 827b2eb7a9..0c9e6af07b 100644 --- a/guix/scripts/search.scm +++ b/guix/scripts/search.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2019 Ludovic Courtès +;;; Copyright © 2019, 2020 Ludovic Courtès ;;; ;;; This file is part of GNU Guix. ;;; @@ -57,7 +57,9 @@ This is an alias for 'guix package -s'.\n")) (member "load-path" (option-names option))) %standard-build-options))) -(define (guix-search . args) +(define-command (guix-search . args) + (synopsis "search for packages") + (define (handle-argument arg result) ;; Treat all non-option arguments as regexps. (cons `(query search ,(or arg "")) diff --git a/guix/scripts/show.scm b/guix/scripts/show.scm index a2b0030a63..535d03c1a6 100644 --- a/guix/scripts/show.scm +++ b/guix/scripts/show.scm @@ -57,7 +57,9 @@ This is an alias for 'guix package --show='.\n")) (member "load-path" (option-names option))) %standard-build-options))) -(define (guix-show . args) +(define-command (guix-show . args) + (synopsis "show information about packages") + (define (handle-argument arg result) ;; Treat all non-option arguments as regexps. (cons `(query show ,arg) diff --git a/guix/scripts/size.scm b/guix/scripts/size.scm index c42f4f7782..2ed5d3cdd0 100644 --- a/guix/scripts/size.scm +++ b/guix/scripts/size.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2015, 2016, 2017, 2018, 2019 Ludovic Courtès +;;; Copyright © 2015, 2016, 2017, 2018, 2019, 2020 Ludovic Courtès ;;; Copyright © 2019 Simon Tournier ;;; ;;; This file is part of GNU Guix. @@ -298,7 +298,10 @@ Report the size of the PACKAGE or STORE-ITEM, with its dependencies.\n")) ;;; Entry point. ;;; -(define (guix-size . args) +(define-command (guix-size . args) + (category advanced) + (synopsis "profile the on-disk size of packages") + (with-error-handling (let* ((opts (parse-command-line args %options (list %default-options) #:build-options? #f)) diff --git a/guix/scripts/substitute.scm b/guix/scripts/substitute.scm index f9d19fd735..1462ce9918 100755 --- a/guix/scripts/substitute.scm +++ b/guix/scripts/substitute.scm @@ -20,6 +20,7 @@ (define-module (guix scripts substitute) #:use-module (guix ui) + #:use-module (guix scripts) #:use-module (guix store) #:use-module (guix utils) #:use-module (guix combinators) @@ -1095,8 +1096,10 @@ default value." (unless (string->uri uri) (leave (G_ "~a: invalid URI~%") uri))) -(define (guix-substitute . args) - "Implement the build daemon's substituter protocol." +(define-command (guix-substitute . args) + (category internal) + (synopsis "implement the build daemon's substituter protocol") + (define print-build-trace? (match (or (find-daemon-option "untrusted-print-extended-build-trace") (find-daemon-option "print-extended-build-trace")) diff --git a/guix/scripts/system.scm b/guix/scripts/system.scm index 3222a53c8f..2a514166eb 100644 --- a/guix/scripts/system.scm +++ b/guix/scripts/system.scm @@ -1240,7 +1240,9 @@ argument list and OPTS is the option alist." ;; need an operating system configuration file. (else (process-action command args opts)))) -(define (guix-system . args) +(define-command (guix-system . args) + (synopsis "build and deploy full operating systems") + (define (parse-sub-command arg result) ;; Parse sub-command ARG and augment RESULT accordingly. (if (assoc-ref result 'action) diff --git a/guix/scripts/time-machine.scm b/guix/scripts/time-machine.scm index 441673b780..0d27414702 100644 --- a/guix/scripts/time-machine.scm +++ b/guix/scripts/time-machine.scm @@ -128,7 +128,9 @@ Execute COMMAND ARGS... in an older version of Guix.\n")) ;;; Entry point. ;;; -(define (guix-time-machine . args) +(define-command (guix-time-machine . args) + (synopsis "run commands from a different revision") + (with-error-handling (with-git-error-handling (let* ((opts (parse-args args)) diff --git a/guix/scripts/upgrade.scm b/guix/scripts/upgrade.scm index d2784669be..8c7abd133a 100644 --- a/guix/scripts/upgrade.scm +++ b/guix/scripts/upgrade.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2019 Ludovic Courtès +;;; Copyright © 2019, 2020 Ludovic Courtès ;;; Copyright © 2020 Jakub Kądziołka ;;; ;;; This file is part of GNU Guix. @@ -67,7 +67,9 @@ This is an alias for 'guix package -u'.\n")) %transformation-options %standard-build-options))) -(define (guix-upgrade . args) +(define-command (guix-upgrade . args) + (synopsis "upgrade packages to their latest version") + (define (handle-argument arg result arg-handler) ;; Accept at most one non-option argument, and treat it as an upgrade ;; regexp. diff --git a/guix/scripts/weather.scm b/guix/scripts/weather.scm index 3035ff6ca8..48207d4205 100644 --- a/guix/scripts/weather.scm +++ b/guix/scripts/weather.scm @@ -495,7 +495,9 @@ SERVER. Display information for packages with at least THRESHOLD dependents." ;;; Entry point. ;;; -(define (guix-weather . args) +(define-command (guix-weather . args) + (synopsis "report on the available of pre-built package binaries") + (define (package-list opts) ;; Return the package list specified by OPTS. (let ((files (filter-map (match-lambda diff --git a/guix/ui.scm b/guix/ui.scm index efc3f39186..4d90a47bb9 100644 --- a/guix/ui.scm +++ b/guix/ui.scm @@ -60,6 +60,7 @@ ;; Avoid "overrides core binding" warning. delete)) #:use-module (srfi srfi-1) + #:use-module (srfi srfi-9 gnu) #:use-module (srfi srfi-11) #:use-module (srfi srfi-19) #:use-module (srfi srfi-26) @@ -1988,6 +1989,44 @@ optionally contain a version number and an output name, as in these examples: (G_ "Try `guix --help' for more information.~%")) (exit 1)) +;; Representation of a 'guix' command. +(define-immutable-record-type + (command name synopsis category) + command? + (name command-name) + (synopsis command-synopsis) + (category command-category)) + +(define (source-file-command file) + "Read FILE, a Scheme source file, and return either a object based +on the 'define-command' top-level form found therein, or #f if FILE does not +contain a 'define-command' form." + (define command-name + (match (string-split file #\/) + ((_ ... "guix" "scripts" name) + (list (file-sans-extension name))) + ((_ ... "guix" "scripts" first second) + (list first (file-sans-extension second))))) + + ;; The strategy here is to parse FILE. This is much cheaper than a + ;; technique based on run-time introspection where we'd load FILE and all + ;; the modules it depends on. + (call-with-input-file file + (lambda (port) + (let loop () + (match (read port) + (('define-command _ ('synopsis synopsis) + _ ...) + (command command-name synopsis 'main)) + (('define-command _ + ('category category) ('synopsis synopsis) + _ ...) + (command command-name synopsis category)) + ((? eof-object?) + #f) + (_ + (loop))))))) + (define (command-files) "Return the list of source files that define Guix sub-commands." (define directory @@ -1999,28 +2038,50 @@ optionally contain a version number and an output name, as in these examples: (cut string-suffix? ".scm" <>)) (if directory - (scandir directory dot-scm?) + (map (cut string-append directory "/" <>) + (scandir directory dot-scm?)) '())) (define (commands) - "Return the list of Guix command names." - (map (compose (cut string-drop-right <> 4) - basename) - (command-files))) + "Return the list of commands, alphabetically sorted." + (filter-map source-file-command (command-files))) (define (show-guix-help) (define (internal? command) (member command '("substitute" "authenticate" "offload" "perform-download"))) + (define (display-commands commands) + (let* ((names (map (lambda (command) + (string-join (command-name command))) + commands)) + (max-width (reduce max 0 (map string-length names)))) + (for-each (lambda (name command) + (format #t " ~a ~a~%" + (string-pad-right name max-width) + (G_ (command-synopsis command)))) + names + commands))) + + (define (category-predicate category) + (lambda (command) + (eq? category (command-category command)))) + (format #t (G_ "Usage: guix COMMAND ARGS... Run COMMAND with ARGS.\n")) (newline) (format #t (G_ "COMMAND must be one of the sub-commands listed below:\n")) (newline) - ;; TODO: Display a synopsis of each command. - (format #t "~{ ~a~%~}" (sort (remove internal? (commands)) - string) id 1kDNnO-0003P9-G3 for submit@debbugs.gnu.org; Wed, 02 Sep 2020 04:07:07 -0400 Received: from flashner.co.il ([178.62.234.194]:41430) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDNnJ-0003O5-HP for 43159@debbugs.gnu.org; Wed, 02 Sep 2020 04:07:05 -0400 Received: from localhost (unknown [31.210.181.177]) by flashner.co.il (Postfix) with ESMTPSA id 93CEA40087; Wed, 2 Sep 2020 08:06:55 +0000 (UTC) Date: Wed, 2 Sep 2020 11:06:22 +0300 From: Efraim Flashner To: Ludovic =?utf-8?Q?Court=C3=A8s?= Subject: Re: [bug#43159] [PATCH 0/2] Make 'guix help' helpful Message-ID: <20200902080622.GI856@E5400> References: <20200901203520.21103-1-ludo@gnu.org> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="cN519qCC4CN1mUcX" Content-Disposition: inline In-Reply-To: <20200901203520.21103-1-ludo@gnu.org> X-PGP-Key-ID: 0x41AAE7DCCA3D8351 X-PGP-Key: https://flashner.co.il/~efraim/efraim_flashner.asc X-PGP-Fingerprint: A28B F40C 3E55 1372 662D 14F7 41AA E7DC CA3D 8351 X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 43159 Cc: 43159@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --cN519qCC4CN1mUcX Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Tue, Sep 01, 2020 at 10:35:20PM +0200, Ludovic Court=C3=A8s wrote: > Hey Guix! >=20 > Here=E2=80=99s another long-overdue change that was brought to my > attention: making =E2=80=98guix help=E2=80=99 show a synopsis of each com= mand. > While at it, it also groups them in categories (I more or > less followed the manual, but there=E2=80=99s prolly room for > improvement, like a =E2=80=98packaging=E2=80=99 category maybe?): >=20 I dislike the idea that some commands are only for developers and some commands are "too advanced for the common user" (my words, not yours). Before bikeshedding about where the options should be, how about: commands for developers -> commands related to building advanced usage -> commands related to verification This way they're still "commands for everybody" and they're more descriptive than just "advanced" "expert" and "debug" style headers. > --8<---------------cut here---------------start------------->8--- > $ ./pre-inst-env guix help > Usage: guix COMMAND ARGS... > Run COMMAND with ARGS. >=20 > COMMAND must be one of the sub-commands listed below: >=20 > main commands: > deploy deploy operating systems on a set of machines > describe describe the channel revisions currently used > gc invoke the garbage collector > install install packages > package manage packages and profiles > pull pull the latest revision of Guix > remove removed installed packages > search search for packages > show show information about packages > system build and deploy full operating systems > time-machine run commands from a different revision > upgrade upgrade packages to their latest version > weather report on the available of pre-built package binaries >=20 > commands for developers: > build build packages or derivations without installing them > container run code in containers created by 'guix environment -C' > edit view and edit package definitions > environment spawn one-off software environments > import import a package definition from an external repository > pack create application bundles > refresh update existing package definitions >=20 > advanced usage: > archive manipulate, export, and import normalized archives (nars) > challenge challenge substitute servers, comparing their binaries > copy copy store items remotely over SSH > download download a file to the store and print its hash > git operate on Git repositories > graph view and query package dependency graphs > hash compute the cryptographic hash of a file > lint validate package definitions > offload set up and operate build offloading > processes list currently running sessions > publish publish build results over HTTP > repl read-eval-print loop (REPL) for interactive programming > size profile the on-disk size of packages >=20 > Report bugs to: bug-guix@gnu.org. > GNU Guix home page: > General help using Guix and GNU software: > --8<---------------cut here---------------end--------------->8--- >=20 > Much more=E2=80=A6 helpful than what we currently have, no? :-) >=20 > This works by introducing a new =E2=80=98define-command=E2=80=99 macro th= at each > command now uses and where it defines its synopsis. =E2=80=98guix help= =E2=80=99 > actually reads files in search of =E2=80=98define-command=E2=80=99, which= is cheaper > than loading each module and doing some sort of introspection. >=20 > The URL shown at the end (=E2=80=9CGeneral help=E2=80=9D) is also changed= , as was > rightfully suggested by zimoun a while back. >=20 > Thoughts? >=20 > Ludo=E2=80=99. >=20 > PS: We can talk about categories, but make sure to turn on the > bikeshedding limitation mode of your mail client. :-) >=20 > Ludovic Court=C3=A8s (2): > scripts: Use 'define-command' and have 'guix help' use that. > ui: '--help' output links to . >=20 > guix/scripts.scm | 29 ++++++++++- > guix/scripts/archive.scm | 5 +- > guix/scripts/authenticate.scm | 8 ++- > guix/scripts/build.scm | 5 +- > guix/scripts/challenge.scm | 5 +- > guix/scripts/container.scm | 6 ++- > guix/scripts/copy.scm | 5 +- > guix/scripts/deploy.scm | 3 +- > guix/scripts/describe.scm | 3 +- > guix/scripts/download.scm | 5 +- > guix/scripts/edit.scm | 7 ++- > guix/scripts/environment.scm | 5 +- > guix/scripts/gc.scm | 4 +- > guix/scripts/git.scm | 6 ++- > guix/scripts/graph.scm | 5 +- > guix/scripts/hash.scm | 5 +- > guix/scripts/import.scm | 8 ++- > guix/scripts/install.scm | 6 ++- > guix/scripts/lint.scm | 5 +- > guix/scripts/offload.scm | 6 ++- > guix/scripts/pack.scm | 5 +- > guix/scripts/package.scm | 4 +- > guix/scripts/perform-download.scm | 18 ++++--- > guix/scripts/processes.scm | 4 +- > guix/scripts/publish.scm | 5 +- > guix/scripts/pull.scm | 4 +- > guix/scripts/refresh.scm | 7 ++- > guix/scripts/remove.scm | 6 ++- > guix/scripts/repl.scm | 5 +- > guix/scripts/search.scm | 6 ++- > guix/scripts/show.scm | 4 +- > guix/scripts/size.scm | 7 ++- > guix/scripts/substitute.scm | 7 ++- > guix/scripts/system.scm | 4 +- > guix/scripts/time-machine.scm | 4 +- > guix/scripts/upgrade.scm | 6 ++- > guix/scripts/weather.scm | 4 +- > guix/ui.scm | 82 +++++++++++++++++++++++++++---- > 38 files changed, 249 insertions(+), 64 deletions(-) >=20 > --=20 > 2.28.0 >=20 >=20 >=20 >=20 --=20 Efraim Flashner =D7=90=D7=A4=D7=A8=D7=99=D7=9D = =D7=A4=D7=9C=D7=A9=D7=A0=D7=A8 GPG key =3D A28B F40C 3E55 1372 662D 14F7 41AA E7DC CA3D 8351 Confidentiality cannot be guaranteed on emails sent or received unencrypted --cN519qCC4CN1mUcX Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAABCgAdFiEEoov0DD5VE3JmLRT3Qarn3Mo9g1EFAl9PUnsACgkQQarn3Mo9 g1FDuxAAkbQQSp9tou8KxdrlxF2CoEKt+XsKsBaPwSf+jV0N6bneve9QuI8cvsRb dzjYdbOvF09t32HrDexCv/uytGrPxF/ldQHzejxevObqPJyPjnbc2KHaGg15FWZu yU12/SMkXLqIW+JRjjWFsLbH8gQlWmG4r6Q17RYY/IT22TExJWn7uHTUiwcWbh/p MeVc1KwLGx0TwEv5eU7n/jJNyoSg9ABB2c8njmqoAbCI+10f1NoTcKFIWFeOhq70 Bd1of3CXZ2MUm0TFVK8rLEs8IfuPVLkok6tbKZIKBKdOob3zuQaexFQQkI7hvCLL HTI85GeIj73rEZQni2DeLe/+4RkIIt1k1KrvC7HDVmXRNBd8QwMyJ3vF7YFE1NGZ am64YA6rJwwyYsrLLFD/WgvPW3Hf2HaprmiGSr4sup4lDjToCwQUJvYcbHQtNJjF S1tcqRKtlejKKEKi86cpDA1arCxgKPeXOTya9O593cz0KADz1AZ2kA/yP0Zx6W32 4G0485+3QzRtdVh3R3/94GEqXr0Fvd5ZqvNwgabweOwDIfYjkdKCkH9khS4XeNgL fLHSdEOnDQ/JOcAxKGHi3yThT0kf+BRkEj4zG5qi9j+No7Dv+mHEchiW3vDpWpY5 n6zHiPicgPiyaaGc//fOliwUAmUgfdYI9nuNBR73AJrVbN26Lrw= =xtBQ -----END PGP SIGNATURE----- --cN519qCC4CN1mUcX-- From debbugs-submit-bounces@debbugs.gnu.org Wed Sep 02 05:50:30 2020 Received: (at 43159) by debbugs.gnu.org; 2 Sep 2020 09:50:30 +0000 Received: from localhost ([127.0.0.1]:58364 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDPPR-0007E5-N5 for submit@debbugs.gnu.org; Wed, 02 Sep 2020 05:50:30 -0400 Received: from eggs.gnu.org ([209.51.188.92]:58814) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDPPP-0007Di-AZ for 43159@debbugs.gnu.org; Wed, 02 Sep 2020 05:50:28 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:42365) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kDPPJ-00075b-CU; Wed, 02 Sep 2020 05:50:21 -0400 Received: from [2a01:e0a:1d:7270:af76:b9b:ca24:c465] (port=53528 helo=ribbon) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kDPPI-0005gD-Ki; Wed, 02 Sep 2020 05:50:21 -0400 From: =?utf-8?Q?Ludovic_Court=C3=A8s?= To: Efraim Flashner Subject: Re: [bug#43159] [PATCH 0/2] Make 'guix help' helpful References: <20200901203520.21103-1-ludo@gnu.org> <20200902080622.GI856@E5400> X-URL: http://www.fdn.fr/~lcourtes/ X-Revolutionary-Date: 17 Fructidor an 228 de la =?utf-8?Q?R=C3=A9volution?= X-PGP-Key-ID: 0x090B11993D9AEBB5 X-PGP-Key: http://www.fdn.fr/~lcourtes/ludovic.asc X-PGP-Fingerprint: 3CE4 6455 8A84 FDC6 9DB4 0CFB 090B 1199 3D9A EBB5 X-OS: x86_64-pc-linux-gnu Date: Wed, 02 Sep 2020 11:50:17 +0200 In-Reply-To: <20200902080622.GI856@E5400> (Efraim Flashner's message of "Wed, 2 Sep 2020 11:06:22 +0300") Message-ID: <87a6y87bja.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 43159 Cc: 43159@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Hi, Efraim Flashner skribis: > On Tue, Sep 01, 2020 at 10:35:20PM +0200, Ludovic Court=C3=A8s wrote: >> Hey Guix! >>=20 >> Here=E2=80=99s another long-overdue change that was brought to my >> attention: making =E2=80=98guix help=E2=80=99 show a synopsis of each co= mmand. >> While at it, it also groups them in categories (I more or >> less followed the manual, but there=E2=80=99s prolly room for >> improvement, like a =E2=80=98packaging=E2=80=99 category maybe?): >>=20 > > I dislike the idea that some commands are only for developers and some > commands are "too advanced for the common user" (my words, not yours). Yeah, I=E2=80=99m ambivalent about this as well. > Before bikeshedding about where the options should be, how about: > commands for developers -> commands related to building Rather, =E2=80=9Ccommands for development=E2=80=9C, because that=E2=80=99s = really what =E2=80=98guix environment=E2=80=99 is about, for instance, but saying =E2=80=98developmen= t=E2=80=99 rather than =E2=80=98developers=E2=80=99 is probably wise. > advanced usage -> commands related to verification Well that only works for =E2=80=98challenge=E2=80=99 (which I=E2=80=99d lik= e to put in the hands of =E2=80=98normal=E2=80=99 users, so I=E2=80=99m not comfortable with the = =E2=80=98advanced=E2=80=99 label, but OTOH, it=E2=80=99s clearly not one of the commands you=E2=80=99d begin with= .) What about archive, copy, download, etc.? > This way they're still "commands for everybody" and they're more > descriptive than just "advanced" "expert" and "debug" style headers. Understood. Thanks for your feedback! Ludo=E2=80=99. From debbugs-submit-bounces@debbugs.gnu.org Wed Sep 02 07:10:45 2020 Received: (at 43159) by debbugs.gnu.org; 2 Sep 2020 11:10:45 +0000 Received: from localhost ([127.0.0.1]:58490 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDQf7-0000s7-Bb for submit@debbugs.gnu.org; Wed, 02 Sep 2020 07:10:45 -0400 Received: from flashner.co.il ([178.62.234.194]:41796) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDQf4-0000rs-Kc for 43159@debbugs.gnu.org; Wed, 02 Sep 2020 07:10:44 -0400 Received: from localhost (unknown [31.210.181.177]) by flashner.co.il (Postfix) with ESMTPSA id 7F6A3403E0; Wed, 2 Sep 2020 11:10:36 +0000 (UTC) Date: Wed, 2 Sep 2020 14:09:53 +0300 From: Efraim Flashner To: Ludovic =?utf-8?Q?Court=C3=A8s?= Subject: Re: [bug#43159] [PATCH 0/2] Make 'guix help' helpful Message-ID: <20200902110953.GB24305@E5400> References: <20200901203520.21103-1-ludo@gnu.org> <20200902080622.GI856@E5400> <87a6y87bja.fsf@gnu.org> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="NtwzykIc2mflq5ck" Content-Disposition: inline In-Reply-To: <87a6y87bja.fsf@gnu.org> X-PGP-Key-ID: 0x41AAE7DCCA3D8351 X-PGP-Key: https://flashner.co.il/~efraim/efraim_flashner.asc X-PGP-Fingerprint: A28B F40C 3E55 1372 662D 14F7 41AA E7DC CA3D 8351 X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 43159 Cc: 43159@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --NtwzykIc2mflq5ck Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Wed, Sep 02, 2020 at 11:50:17AM +0200, Ludovic Court=C3=A8s wrote: > Hi, >=20 > Efraim Flashner skribis: >=20 > > On Tue, Sep 01, 2020 at 10:35:20PM +0200, Ludovic Court=C3=A8s wrote: > >> Hey Guix! > >>=20 > >> Here=E2=80=99s another long-overdue change that was brought to my > >> attention: making =E2=80=98guix help=E2=80=99 show a synopsis of each = command. > >> While at it, it also groups them in categories (I more or > >> less followed the manual, but there=E2=80=99s prolly room for > >> improvement, like a =E2=80=98packaging=E2=80=99 category maybe?): > >>=20 > > > > I dislike the idea that some commands are only for developers and some > > commands are "too advanced for the common user" (my words, not yours). >=20 > Yeah, I=E2=80=99m ambivalent about this as well. >=20 > > Before bikeshedding about where the options should be, how about: > > commands for developers -> commands related to building >=20 > Rather, =E2=80=9Ccommands for development=E2=80=9C, because that=E2=80=99= s really what =E2=80=98guix > environment=E2=80=99 is about, for instance, but saying =E2=80=98developm= ent=E2=80=99 rather > than =E2=80=98developers=E2=80=99 is probably wise. >=20 > > advanced usage -> commands related to verification >=20 > Well that only works for =E2=80=98challenge=E2=80=99 (which I=E2=80=99d l= ike to put in the hands > of =E2=80=98normal=E2=80=99 users, so I=E2=80=99m not comfortable with th= e =E2=80=98advanced=E2=80=99 label, but > OTOH, it=E2=80=99s clearly not one of the commands you=E2=80=99d begin wi= th.) >=20 > What about archive, copy, download, etc.? >=20 It seemed loosely related. If you're running 'guix pull; guix upgrade' you're not first running 'guix download https://path/to/source.tar.xz' or copying packages between machines or challenging the reproducibility of the packages. That's for after you have the packages you want in your profile or environment. > > This way they're still "commands for everybody" and they're more > > descriptive than just "advanced" "expert" and "debug" style headers. >=20 > Understood. >=20 > Thanks for your feedback! >=20 > Ludo=E2=80=99. --=20 Efraim Flashner =D7=90=D7=A4=D7=A8=D7=99=D7=9D = =D7=A4=D7=9C=D7=A9=D7=A0=D7=A8 GPG key =3D A28B F40C 3E55 1372 662D 14F7 41AA E7DC CA3D 8351 Confidentiality cannot be guaranteed on emails sent or received unencrypted --NtwzykIc2mflq5ck Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAABCgAdFiEEoov0DD5VE3JmLRT3Qarn3Mo9g1EFAl9PfXwACgkQQarn3Mo9 g1HJjQ//Z2rWEJhi8x0bG4hr0TZ6wQHuRkMaXBAh3SypSk3QEmn6LeGC96qBDnh1 N2oVpg519U5lVkOsnbwQWy8XiKq72Itd04+DE07mfoqn3JpzaVRdQz2Mc+l0MOZM A2/ZqO1Ikw5GinoPnq441WlI+XkkbN4tB0pdeNv83P4QTv1AIZIq4fj6SLCRi41D k61l7mcUUEjniLniUmFQOi6ge7e6iscgs6j/cG2oL6dvH0cL/LNAnz4aQ877DswA Pop2anp3MzPrK1EMKpuUfIu9cKI2C8i1kNByGGvdBnCA6yr31Sfd9wCa8/qQf/6i sfsb3CAxjp2fJL4Q5hEGQ73kR0r5mfgwbw35wAVMF0hA4p8VOCIiiO5n5nOqZLGh k6ylLE4wY7KPgDAo2zZRrFb+NM5SKFwpZlYI/l1/lkeGBL0DVKcnRy/NDpjGrqnO Ee2C2jeCyQrIbZaZvPbLoXRA3bR99A2i5tvVDSp5bFXHug7fi8fqWwiW/RiwPxef LaAnfgLXQMck2iUG8YCeMuz2acRaPctYItPIuYdU1ci5VIVzM6Y0O5aynWQBaDvR gYH2Z189p98/ye+dkGNPdx7wX8yAwrtW2Ef740qmWouc4T14g8iPY76MfelzBe9O QeFGpl04RRweZgFgeGD4woFrCkZP3DGt58VLwIusav3Zveg1Dgk= =iORf -----END PGP SIGNATURE----- --NtwzykIc2mflq5ck-- From debbugs-submit-bounces@debbugs.gnu.org Wed Sep 02 14:24:28 2020 Received: (at 43159) by debbugs.gnu.org; 2 Sep 2020 18:24:28 +0000 Received: from localhost ([127.0.0.1]:60682 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDXQq-0005yA-9w for submit@debbugs.gnu.org; Wed, 02 Sep 2020 14:24:28 -0400 Received: from mail-qt1-f194.google.com ([209.85.160.194]:39775) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDXQo-0005xw-3z for 43159@debbugs.gnu.org; Wed, 02 Sep 2020 14:24:26 -0400 Received: by mail-qt1-f194.google.com with SMTP id 92so4331996qtb.6 for <43159@debbugs.gnu.org>; Wed, 02 Sep 2020 11:24:26 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-transfer-encoding; bh=SoVQ4+rAgpIg90+4guBmGn0lLf9ZRNJP/sdsAKqAQWE=; b=bZta9C1q60WHu0Qj4jQIUd/hQLrSiywaijhdLST0Oj48KCJDAY455J8zBS5/bVhg9h pJghcwa8Aqo23yq+5sXEtgN1QWg0Me5BZLK0Tjk4RBMAr0IqW1IopZjVfe6ZokqSB0t/ tFn4Ektqt16I4RaA2L0OjThqaPU5pEUwzAiOzNZv3cZllma5peM+g2J8qBwB4lVlLLsn 5SwFOsJvPS91rbY3r2OxmN0o2USIbYrFHKdvQVluCXRDfQaDwFcIP7voKhE6VORXfCMZ AbGuTKn866iq+wh3YJ2d7G+BqcoHSk4fGPG5iTKmNtAUIsF2+gvGqtO6Z3mNULGnGd/C XxNg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version:content-transfer-encoding; bh=SoVQ4+rAgpIg90+4guBmGn0lLf9ZRNJP/sdsAKqAQWE=; b=UTB/aVPp6ItVtRVGc7KjaaHMK4nCmtuZy7JQ/BzOpfBoh8fWIAnbQGkWRgXsGTDsOw hn1BBmcOWIiEU8xwfNn5nzXw9QIfh1AW1zq7XutZQKKMSt10AdYJ8thUkiaYDBRX4rxf vdfJd0lOUFojeQRg0Co4Y/lDDZLOi5JaUbis01rx+xk1fOO7ubGRib1U4CRmJt5shg0J /bdjCQgnqGx0NLHns3MlatzfiyoEWsXW5LU8Axtcy6yHEwqS1y7YECj6m8XI803hk3Ow krlF8YeYmxQOwDOPJcQcQmujRKaQN/LXkEAtJcRLaV5bemLGatmcmfDdpgToLOIfUpWy hidw== X-Gm-Message-State: AOAM530xc8PdN0YpRZdoR4CH/aNTmnx+Dh6RC+s0eRkucRVtzXDhTunn kyoKfC0IjUWE4ZBRVy51zOlr0YtlPl0Ibg== X-Google-Smtp-Source: ABdhPJw6isFA4MJE9G02iHf8lXMCw4wtqzZEedRf81RvCQsqFBacLqTuIi7ReIU2jr4hHg/kyGkyuA== X-Received: by 2002:aed:3223:: with SMTP id y32mr8047690qtd.341.1599071060313; Wed, 02 Sep 2020 11:24:20 -0700 (PDT) Received: from hurd (dsl-10-133-254.b2b2c.ca. [72.10.133.254]) by smtp.gmail.com with ESMTPSA id u18sm143528qtk.61.2020.09.02.11.24.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 02 Sep 2020 11:24:19 -0700 (PDT) From: Maxim Cournoyer To: Ludovic =?utf-8?Q?Court=C3=A8s?= Subject: Re: [bug#43159] [PATCH 1/2] scripts: Use 'define-command' and have 'guix help' use that. References: <20200901203520.21103-1-ludo@gnu.org> <20200901204136.21375-1-ludo@gnu.org> Date: Wed, 02 Sep 2020 14:24:34 -0400 In-Reply-To: <20200901204136.21375-1-ludo@gnu.org> ("Ludovic \=\?utf-8\?Q\?Cou\?\= \=\?utf-8\?Q\?rt\=C3\=A8s\=22's\?\= message of "Tue, 1 Sep 2020 22:41:35 +0200") Message-ID: <87r1rk595p.fsf@gmail.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 43159 Cc: 43159@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Ludovic Court=C3=A8s writes: > This changes 'guix help' to print a short synopsis for each command and > to group commands by category. [...] > diff --git a/guix/scripts.scm b/guix/scripts.scm > index 8534948892..013b775818 100644 > --- a/guix/scripts.scm > +++ b/guix/scripts.scm > @@ -34,7 +34,10 @@ > #:use-module (srfi srfi-19) > #:use-module (srfi srfi-37) > #:use-module (ice-9 match) > - #:export (args-fold* > + #:export (synopsis > + category > + define-command > + args-fold* > parse-command-line > maybe-build > build-package > @@ -50,6 +53,30 @@ > ;;; > ;;; Code: > > +;; Syntactic keywords. > +(define synopsis 'command-synopsis) > +(define category 'command-category) Are these definition really necessary/useful? I would have thought having category and synopsis understood as literals in the define-command syntax was enough? > +(define-syntax define-command > + (syntax-rules (category synopsis) > + "Define the given command as a procedure along with its synopsis and, > +optionally, its category. The synopsis becomes the docstring of the > +procedure, but both the category and synopsis are meant to be read (pars= ed) by > +'guix help'." > + ;; The (synopsis ...) form is here so that xgettext sees those strin= gs as > + ;; translatable. > + ((_ (name . args) > + (synopsis doc) body ...) > + (define (name . args) > + doc > + body ...)) > + ((_ (name . args) > + (category _) > + (synopsis doc) body ...) > + (define (name . args) > + doc > + body ...)))) > + > (define (args-fold* args options unrecognized-option-proc operand-proc .= seeds) > "A wrapper on top of `args-fold' that does proper user-facing error > reporting." > diff --git a/guix/scripts/archive.scm b/guix/scripts/archive.scm > index f3b86fba14..8796774a01 100644 > --- a/guix/scripts/archive.scm > +++ b/guix/scripts/archive.scm > @@ -355,7 +355,10 @@ output port." > ;;; Entry point. > ;;; > > -(define (guix-archive . args) > +(define-command (guix-archive . args) > + (category advanced) It'd be helpful if the category was an enum to keep the set of categories focused and helpful. [...] > --- a/guix/scripts/weather.scm > +++ b/guix/scripts/weather.scm > @@ -495,7 +495,9 @@ SERVER. Display information for packages with at lea= st THRESHOLD dependents." > ;;; Entry point. > ;;; > > -(define (guix-weather . args) > +(define-command (guix-weather . args) > + (synopsis "report on the available of pre-built package binaries") ^ availability [...] > +(define (source-file-command file) > + "Read FILE, a Scheme source file, and return either a object= based > +on the 'define-command' top-level form found therein, or #f if FILE does= not > +contain a 'define-command' form." > + (define command-name > + (match (string-split file #\/) > + ((_ ... "guix" "scripts" name) > + (list (file-sans-extension name))) > + ((_ ... "guix" "scripts" first second) > + (list first (file-sans-extension second))))) It'd be better if an else clause threw an informative error, especially since the restriction on file name is not otherwise documented. > + ;; The strategy here is to parse FILE. This is much cheaper than a > + ;; technique based on run-time introspection where we'd load FILE and = all > + ;; the modules it depends on. Interesting! Have you measure it? I would have thought loading a couple optimized byte code modules could have been nearly as fast as parsing files manually. If so, I think it'd be preferable to use introspection rather than implement a custom parser. > + (call-with-input-file file > + (lambda (port) > + (let loop () > + (match (read port) > + (('define-command _ ('synopsis synopsis) > + _ ...) > + (command command-name synopsis 'main)) > + (('define-command _ > + ('category category) ('synopsis synopsis) > + _ ...) > + (command command-name synopsis category)) > + ((? eof-object?) > + #f) > + (_ > + (loop))))))) > + [...] > + (define (display-commands commands) > + (let* ((names (map (lambda (command) > + (string-join (command-name command))) > + commands)) > + (max-width (reduce max 0 (map string-length names)))) You can drop reduce and use (max (map string-length names)) instead. Maxim From debbugs-submit-bounces@debbugs.gnu.org Wed Sep 02 14:27:27 2020 Received: (at 43159) by debbugs.gnu.org; 2 Sep 2020 18:27:27 +0000 Received: from localhost ([127.0.0.1]:60686 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDXTi-00062O-Sf for submit@debbugs.gnu.org; Wed, 02 Sep 2020 14:27:27 -0400 Received: from mail-qk1-f194.google.com ([209.85.222.194]:38166) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDXTg-00062A-Ep for 43159@debbugs.gnu.org; Wed, 02 Sep 2020 14:27:25 -0400 Received: by mail-qk1-f194.google.com with SMTP id d20so635235qka.5 for <43159@debbugs.gnu.org>; Wed, 02 Sep 2020 11:27:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-transfer-encoding; bh=bKleGJalCQp0NlYcvPV+78KqaWGrM5HbxVqOfN/ngB8=; b=MwABFmGtBdflb2M+HwLjVsbl50HsuqUYsRA4dK+9zDjMuAaQPjKBlZLz9/JfkBl6Cy FsncFXfyEnwp2yGFTBANyUBc6swMU3ovCkal/C7PyVgNo7cHIX1AXhchi+cUY+gIhTbY wYd5MQk919HeHXAdLnTlU4CxalWkny0/E81vf5jK7ykn/jFe5j5hKcONMxzH1FP3Sx8C zJhCJOrAvg6+wTjSSf2Ni/tJY1lgRRPDdLseHCsPASi3sR1GqW2Q5sJi7DThmp95ZJ5e 3V8hx29g7UjHef3YtlRNcQ9aLDfbB2eHoo/sDPxqG6XxD9QEfYJpVYHybw7Yuo5r4Mng QWkA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version:content-transfer-encoding; bh=bKleGJalCQp0NlYcvPV+78KqaWGrM5HbxVqOfN/ngB8=; b=OnArgqeY1doNdmAEExDQ6qXhNq28wqiveb1PkVxhmp9JKHRZL0Gi5U1uFzaCWIxbbv rBy9RBo0fy13GasAZFG8cwJV+YoQR+N1zb2Ppd8QCXJ+KzxfD6IySntUM47W13a27hpr UcVmIsAJQ4xK+TmYnWXGfR7R9espx/GhX6UmqL0RbSFtrCHrioP+lBtcQpy+mNB9vDQv Lq5fXkg3nmlLK533SbNz+mcAx+h4VMWBoyXo2c/kNX9LStcqWgMDvE0Dcb055AskSQqX 2Dd4pK6kttzCaEl9YnmAjKsdgwaB/VNmka1EyXbZGaY6VJx8iER07zzfQy+K9++cwio8 l53A== X-Gm-Message-State: AOAM530pel/+EjdhnmpmqrlLvnfEJUjmQWvObQVgxQ+U0sL7uiZI83Md PnLwJ6xUGkUM44O5zHbvT/qfn26iJxUGFw== X-Google-Smtp-Source: ABdhPJwvKQ9lVsR3GAwWZ18NigwMgZZ6mCmVfkrhERVYBvLcgqrBMBwB8QwAS/i65dUpb6dhXYpWJw== X-Received: by 2002:a37:d41:: with SMTP id 62mr7836121qkn.444.1599071238414; Wed, 02 Sep 2020 11:27:18 -0700 (PDT) Received: from hurd (dsl-10-133-254.b2b2c.ca. [72.10.133.254]) by smtp.gmail.com with ESMTPSA id y3sm306054qkd.132.2020.09.02.11.27.17 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 02 Sep 2020 11:27:17 -0700 (PDT) From: Maxim Cournoyer To: Ludovic =?utf-8?Q?Court=C3=A8s?= Subject: Re: [bug#43159] [PATCH 2/2] ui: '--help' output links to . References: <20200901204136.21375-1-ludo@gnu.org> <20200901204136.21375-2-ludo@gnu.org> Date: Wed, 02 Sep 2020 14:27:32 -0400 In-Reply-To: <20200901204136.21375-2-ludo@gnu.org> ("Ludovic \=\?utf-8\?Q\?Cou\?\= \=\?utf-8\?Q\?rt\=C3\=A8s\=22's\?\= message of "Tue, 1 Sep 2020 22:41:36 +0200") Message-ID: <87mu28590r.fsf@gmail.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 43159 Cc: 43159@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Ludovic Court=C3=A8s writes: > * guix/ui.scm (show-bug-report-information): Link to > instead of . > The former is much more useful and includes links to GNU manuals. > --- > guix/ui.scm | 5 +++-- > 1 file changed, 3 insertions(+), 2 deletions(-) > > diff --git a/guix/ui.scm b/guix/ui.scm > index 4d90a47bb9..87a1925a4b 100644 > --- a/guix/ui.scm > +++ b/guix/ui.scm > @@ -542,8 +542,9 @@ There is NO WARRANTY, to the extent permitted by law. > Report bugs to: ~a.") %guix-bug-report-address) > (format #t (G_ " > ~a home page: <~a>") %guix-package-name %guix-home-page-url) > - (display (G_ " > -General help using GNU software: ")) > + (format #t (G_ " > +General help using Guix and GNU software: <~a>") > + "https://guix.gnu.org/help/") > (newline)) LGTM! Maxim From debbugs-submit-bounces@debbugs.gnu.org Thu Sep 03 09:41:56 2020 Received: (at 43159) by debbugs.gnu.org; 3 Sep 2020 13:41:56 +0000 Received: from localhost ([127.0.0.1]:34094 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDpUy-0007nr-0Y for submit@debbugs.gnu.org; Thu, 03 Sep 2020 09:41:56 -0400 Received: from eggs.gnu.org ([209.51.188.92]:36488) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDpUv-0007ne-Kz for 43159@debbugs.gnu.org; Thu, 03 Sep 2020 09:41:54 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:37560) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kDpUq-0000m9-Bz; Thu, 03 Sep 2020 09:41:48 -0400 Received: from [2a01:e0a:1d:7270:af76:b9b:ca24:c465] (port=33638 helo=ribbon) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kDpUp-0007Lv-Vy; Thu, 03 Sep 2020 09:41:48 -0400 From: =?utf-8?Q?Ludovic_Court=C3=A8s?= To: Maxim Cournoyer Subject: Re: [bug#43159] [PATCH 1/2] scripts: Use 'define-command' and have 'guix help' use that. References: <20200901203520.21103-1-ludo@gnu.org> <20200901204136.21375-1-ludo@gnu.org> <87r1rk595p.fsf@gmail.com> Date: Thu, 03 Sep 2020 15:41:41 +0200 In-Reply-To: <87r1rk595p.fsf@gmail.com> (Maxim Cournoyer's message of "Wed, 02 Sep 2020 14:24:34 -0400") Message-ID: <87blinx9ii.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 43159 Cc: 43159@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Hi Maxim, Maxim Cournoyer skribis: > Ludovic Court=C3=A8s writes: [...] >> +;; Syntactic keywords. >> +(define synopsis 'command-synopsis) >> +(define category 'command-category) > > Are these definition really necessary/useful? I would have thought > having category and synopsis understood as literals in the > define-command syntax was enough? It=E2=80=99s not strictly necessary but it=E2=80=99s been considered =E2=80= =9Cgood practice=E2=80=9D. That allows users to detect name clashes, to rename/hide/etc. syntactic keywords and so on. >> +(define-syntax define-command >> + (syntax-rules (category synopsis) [...] >> -(define (guix-archive . args) >> +(define-command (guix-archive . args) >> + (category advanced) > > It'd be helpful if the category was an enum to keep the set of > categories focused and helpful. Yes, I thought about making it a syntactic keyword; let=E2=80=99s see. >> + ;; The strategy here is to parse FILE. This is much cheaper than a >> + ;; technique based on run-time introspection where we'd load FILE and= all >> + ;; the modules it depends on. > > Interesting! Have you measure it? I would have thought loading a couple > optimized byte code modules could have been nearly as fast as parsing > files manually. If so, I think it'd be preferable to use introspection > rather than implement a custom parser. On a fast recent laptop with an SSD, a load of 0, hot cache, etc., we=E2=80= =99d still be below 1s. But see: --8<---------------cut here---------------start------------->8--- $ strace -c guix help >/dev/null % time seconds usecs/call calls errors syscall ------ ----------- ----------- --------- --------- ------------------ 62.69 0.002698 1 2266 2043 stat 10.94 0.000471 2 161 2 lstat 4.55 0.000196 0 246 mmap 4.51 0.000194 0 330 172 openat [...] ------ ----------- ----------- --------- --------- ------------------ 100.00 0.004304 1 3748 2235 total $ strace -c guile -c '(use-modules (guix scripts system) (guix scripts auth= enticate))' % time seconds usecs/call calls errors syscall ------ ----------- ----------- --------- --------- ------------------ 54.27 0.007799 1 5735 4518 stat 12.00 0.001724 11 149 27 futex 9.06 0.001302 0 1328 651 openat 7.24 0.001040 1 822 mmap [...] ------ ----------- ----------- --------- --------- ------------------ 100.00 0.014371 1 10334 5202 total --8<---------------cut here---------------end--------------->8--- (The 1st run is the current =E2=80=98guix help=E2=80=99; the 2nd run +/- em= ulates what you propose.) Loading all the modules translates into a lot more I/O, roughly an order of magnitude. We=E2=80=99re talking about loading tens of modules just to = get at that synopsis: --8<---------------cut here---------------start------------->8--- scheme@(guile-user)> ,use(guix modules) scheme@(guile-user)> (length (source-module-closure '((guix scripts system)= (guix scripts authenticate)))) $10 =3D 439 scheme@(guile-user)> (length (source-module-closure '((guix scripts) (guix = ui)))) $11 =3D 31 --8<---------------cut here---------------end--------------->8--- Memory usage would also be very different: --8<---------------cut here---------------start------------->8--- $ \time guix help >/dev/null 0.07user 0.01system 0:00.06elapsed 128%CPU (0avgtext+0avgdata 35348maxresid= ent)k 0inputs+0outputs (0major+3906minor)pagefaults 0swaps $ \time guile -c '(use-modules (guix scripts system) (guix scripts authenti= cate))' 0.42user 0.05system 0:00.37elapsed 128%CPU (0avgtext+0avgdata 166916maxresi= dent)k 0inputs+0outputs (0major+15148minor)pagefaults 0swaps --8<---------------cut here---------------end--------------->8--- In summary, while this approach undoubtedly looks awkward to any Lisper, I think it=E2=80=99s a good way to not contribute to the general impression= of sluggishness and resource-hungriness of =E2=80=98guix=E2=80=99 commands. := -) >> + (define (display-commands commands) >> + (let* ((names (map (lambda (command) >> + (string-join (command-name command))) >> + commands)) >> + (max-width (reduce max 0 (map string-length names)))) > > You can drop reduce and use (max (map string-length names)) instead. I could do (apply max (map =E2=80=A6)) but I don=E2=80=99t like the idea of= abusing variadic argument lists in that way=E2=80=94I know, it=E2=80=99s very subje= ctive. ;-) Thanks for your feedback, I=E2=80=99ll send a v2! Ludo=E2=80=99. From debbugs-submit-bounces@debbugs.gnu.org Thu Sep 03 12:40:59 2020 Received: (at 43159) by debbugs.gnu.org; 3 Sep 2020 16:40:59 +0000 Received: from localhost ([127.0.0.1]:36008 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDsIF-00049i-DF for submit@debbugs.gnu.org; Thu, 03 Sep 2020 12:40:59 -0400 Received: from mail-qt1-f194.google.com ([209.85.160.194]:38917) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDsIE-00049U-9b for 43159@debbugs.gnu.org; Thu, 03 Sep 2020 12:40:58 -0400 Received: by mail-qt1-f194.google.com with SMTP id 92so2394570qtb.6 for <43159@debbugs.gnu.org>; Thu, 03 Sep 2020 09:40:58 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc:content-transfer-encoding; bh=Wg7VIipcIHLNFKx5L7jd61IZuC+4KheqGd5wWC0587g=; b=R+nU8vyhMVuIQEta9c6gokWClKRcJNTplJlAtDgWMRBKfReUoR+XObivXkXlJU+K77 VxQLSAa23gO70WqtQx2UEtI/tOOJvh12fdWGlZ0ug/8wM21L5lDX4dfYq6NGgqiu73Ty U808+3HrhCZBV8sIuWIWS5sm1d/rT/qq5DdqpgHJrbAVaLpOlslsNd1mxloOi5vokwyH MGDqs9Nr0Rgh/cTtE/HFbzj09ygazjL74fglQGGZhsINMpT0KjNkUqY7+KH1DuOCUmJW MaiTWLX2uTOZ9et3EcaR8KsGoRzkt/devnLm1ADkZ8GOq92hPZ1WHvXAzEJT/bDCSxAA TRYw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc:content-transfer-encoding; bh=Wg7VIipcIHLNFKx5L7jd61IZuC+4KheqGd5wWC0587g=; b=fMeq05cJGS9lOfxEY+RPhmKB/u8qp8ES/9r0n8U/sbENS/jo7B/Thnq55cVhhPOGTW aQEu/A9L2UG98oI6j8FrC4/nRm64/efrEzCoTmu3xzdd9NSU/prcTF3NuWESuYXuNSS9 o3hJTUOe+fnhhl5fzd3GEeyy6iQa4QwI3HGo41oSCCXxe2N/C7Gu8/QsE4Qyq8YUcDWO YK9OL/n+EDPLu68i2OwvHRT3ivBQ1YVZVeaHuqkwpNvN4UJYN1AyKYJXG0wRrlQHf6TE UqX234PSkE5Awuse7qmKu55zN6ZlIQJwznNUhd4BWi5vDJjgJK728wZAF+FBkDNJKiSW G44A== X-Gm-Message-State: AOAM5300aYpBAkjyOCroCDQB+mg/Uu+9XT3kL67vGsxMXIX1aq5IhSuE yv8hL9pum2TX7Qz93imBVdPhFKY4fOVWL1HU2amQUiGRsdU= X-Google-Smtp-Source: ABdhPJwIFyRbRI4oJkEBTKJgCQd2OLv94eL5bcgeWV89I9DzcvLa4AHNICNTIXTj3maLfi5a4K1iAukvYuDdfwD3YFQ= X-Received: by 2002:ac8:75d3:: with SMTP id z19mr4466941qtq.186.1599151252547; Thu, 03 Sep 2020 09:40:52 -0700 (PDT) MIME-Version: 1.0 References: <20200901203520.21103-1-ludo@gnu.org> In-Reply-To: <20200901203520.21103-1-ludo@gnu.org> From: zimoun Date: Thu, 3 Sep 2020 18:40:41 +0200 Message-ID: Subject: Re: [bug#43159] [PATCH 0/2] Make 'guix help' helpful To: =?UTF-8?Q?Ludovic_Court=C3=A8s?= Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 43159 Cc: 43159@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Hi Ludo, On Tue, 1 Sep 2020 at 22:36, Ludovic Court=C3=A8s wrote: > remove removed installed packages s/removed/remove > environment spawn one-off software environments spawn one-off? > PS: We can talk about categories, but make sure to turn on the > bikeshedding limitation mode of your mail client. :-) Looking for "bikeshedder"? ;-) Category theory is always complicated. :-) It depends what do you mean by developers (or development)? To me, download, hash, lint, repl and size are also commands used on a daily basis for developing. On the other hand, container is claimed to be "experimental" in the manual so it should go in the "advanced" section. Well, instead of "advanced usage", I propose "plumbing commands" Thank you for this change. Cheers, simon From debbugs-submit-bounces@debbugs.gnu.org Mon Sep 07 08:57:16 2020 Received: (at 43159) by debbugs.gnu.org; 7 Sep 2020 12:57:16 +0000 Received: from localhost ([127.0.0.1]:48381 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kFGhl-0007Y7-LH for submit@debbugs.gnu.org; Mon, 07 Sep 2020 08:57:16 -0400 Received: from eggs.gnu.org ([209.51.188.92]:45712) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kFGhh-0007XV-L9 for 43159@debbugs.gnu.org; Mon, 07 Sep 2020 08:57:05 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:41842) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kFGhc-0004hQ-9G; Mon, 07 Sep 2020 08:56:56 -0400 Received: from [2001:660:6102:320:e120:2c8f:8909:cdfe] (port=44066 helo=ribbon) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kFGha-0008A2-I4; Mon, 07 Sep 2020 08:56:55 -0400 From: =?utf-8?Q?Ludovic_Court=C3=A8s?= To: Maxim Cournoyer , Efraim Flashner , zimoun Subject: [PATCHES v2] scripts: Use 'define-command' and have 'guix help' use that. References: <20200901203520.21103-1-ludo@gnu.org> <20200901204136.21375-1-ludo@gnu.org> <87r1rk595p.fsf@gmail.com> Date: Mon, 07 Sep 2020 14:56:47 +0200 In-Reply-To: <87r1rk595p.fsf@gmail.com> (Maxim Cournoyer's message of "Wed, 02 Sep 2020 14:24:34 -0400") Message-ID: <87tuw9iw34.fsf_-_@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 43159 Cc: 43159@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Hi all! Here=E2=80=99s a v2 of the patches, where I tried to take your feedback into account. Changes: =E2=80=A2 Categories that appear in uses of =E2=80=98define-command=E2=80= =99 are now validated at macro-expansion time. =E2=80=A2 (guix scripts) contains an alist of the known categories and =E2=80=98show-help=E2=80=99 traverses it. =E2=80=A2 Changed the label for development commands to =E2=80=9Ccommands= for development=E2=80=9D, and changed =E2=80=9Cadvanced=E2=80=9D to =E2=80= =9Cplumbing=E2=80=9D. =E2=80=A2 Added a =E2=80=9Cpackaging=E2=80=9D category. =E2=80=A2 Fixed the typos you reported. The end result is: --8<---------------cut here---------------start------------->8--- Usage: guix COMMAND ARGS... Run COMMAND with ARGS. COMMAND must be one of the sub-commands listed below: main commands deploy deploy operating systems on a set of machines describe describe the channel revisions currently used gc invoke the garbage collector install install packages package manage packages and profiles pull pull the latest revision of Guix remove remove installed packages search search for packages show show information about packages system build and deploy full operating systems time-machine run commands from a different revision upgrade upgrade packages to their latest version weather report on the availability of pre-built package binaries software development commands container run code in containers created by 'guix environment -C' environment spawn one-off software environments pack create application bundles packaging commands build build packages or derivations without installing them challenge challenge substitute servers, comparing their binaries download download a file to the store and print its hash edit view and edit package definitions graph view and query package dependency graphs hash compute the cryptographic hash of a file import import a package definition from an external repository lint validate package definitions publish publish build results over HTTP refresh update existing package definitions size profile the on-disk size of packages plumbing commands archive manipulate, export, and import normalized archives (nars) copy copy store items remotely over SSH git operate on Git repositories offload set up and operate build offloading processes list currently running sessions repl read-eval-print loop (REPL) for interactive programming Report bugs to: bug-guix@gnu.org. GNU Guix home page: General help using Guix and GNU software: --8<---------------cut here---------------end--------------->8--- Let me know what you think! Thanks, Ludo=E2=80=99. --=-=-= Content-Type: text/x-patch; charset=utf-8 Content-Disposition: inline; filename=0002-scripts-Use-define-command-and-have-guix-help-use-th.patch Content-Transfer-Encoding: quoted-printable >From 63c3ab624d6bee53a0221c35a0e280dd0673d64c Mon Sep 17 00:00:00 2001 From: =3D?UTF-8?q?Ludovic=3D20Court=3DC3=3DA8s?=3D Date: Tue, 1 Sep 2020 22:13:11 +0200 Subject: [PATCH 2/2] scripts: Use 'define-command' and have 'guix help' use that. This changes 'guix help' to print a short synopsis for each command and to group commands by category. * guix/scripts.scm (synopsis, category): New variables. (define-command-categories, define-command): New macros. (%command-categories): New variable. * guix/ui.scm (): New record type. (source-file-command): New procedure. (command-files): Return absolute file names. (commands): Return a list of records. (show-guix-help)[display-commands, category-predicate]: New procedures. Display commands grouped in three categories. * guix/scripts/archive.scm (guix-archive): Use 'define-command'. * guix/scripts/authenticate.scm (guix-authenticate): Likewise. * guix/scripts/build.scm (guix-build): Likewise. * guix/scripts/challenge.scm (guix-challenge): Likewise. * guix/scripts/container.scm (guix-container): Likewise. * guix/scripts/copy.scm (guix-copy): Likewise. * guix/scripts/deploy.scm (guix-deploy): Likewise. * guix/scripts/describe.scm (guix-describe): Likewise. * guix/scripts/download.scm (guix-download): Likewise. * guix/scripts/edit.scm (guix-edit): Likewise. * guix/scripts/environment.scm (guix-environment): Likewise. * guix/scripts/gc.scm (guix-gc): Likewise. * guix/scripts/git.scm (guix-git): Likewise. * guix/scripts/graph.scm (guix-graph): Likewise. * guix/scripts/hash.scm (guix-hash): Likewise. * guix/scripts/import.scm (guix-import): Likewise. * guix/scripts/install.scm (guix-install): Likewise. * guix/scripts/lint.scm (guix-lint): Likewise. * guix/scripts/offload.scm (guix-offload): Likewise. * guix/scripts/pack.scm (guix-pack): Likewise. * guix/scripts/package.scm (guix-package): Likewise. * guix/scripts/perform-download.scm (guix-perform-download): Likewise. * guix/scripts/processes.scm (guix-processes): Likewise. * guix/scripts/publish.scm (guix-publish): Likewise. * guix/scripts/pull.scm (guix-pull): Likewise. * guix/scripts/refresh.scm (guix-refresh): Likewise. * guix/scripts/remove.scm (guix-remove): Likewise. * guix/scripts/repl.scm (guix-repl): Likewise. * guix/scripts/search.scm (guix-search): Likewise. * guix/scripts/show.scm (guix-show): Likewise. * guix/scripts/size.scm (guix-size): Likewise. * guix/scripts/substitute.scm (guix-substitute): Likewise. * guix/scripts/system.scm (guix-system): Likewise. * guix/scripts/time-machine.scm (guix-time-machine): Likewise. * guix/scripts/upgrade.scm (guix-upgrade): Likewise. * guix/scripts/weather.scm (guix-weather): Likewise. --- guix/scripts.scm | 62 +++++++++++++++++++++++- guix/scripts/archive.scm | 5 +- guix/scripts/authenticate.scm | 8 +++- guix/scripts/build.scm | 5 +- guix/scripts/challenge.scm | 5 +- guix/scripts/container.scm | 6 ++- guix/scripts/copy.scm | 5 +- guix/scripts/deploy.scm | 3 +- guix/scripts/describe.scm | 3 +- guix/scripts/download.scm | 5 +- guix/scripts/edit.scm | 7 ++- guix/scripts/environment.scm | 5 +- guix/scripts/gc.scm | 4 +- guix/scripts/git.scm | 6 ++- guix/scripts/graph.scm | 5 +- guix/scripts/hash.scm | 5 +- guix/scripts/import.scm | 8 +++- guix/scripts/install.scm | 6 ++- guix/scripts/lint.scm | 5 +- guix/scripts/offload.scm | 6 ++- guix/scripts/pack.scm | 5 +- guix/scripts/package.scm | 4 +- guix/scripts/perform-download.scm | 18 +++---- guix/scripts/processes.scm | 4 +- guix/scripts/publish.scm | 5 +- guix/scripts/pull.scm | 4 +- guix/scripts/refresh.scm | 7 ++- guix/scripts/remove.scm | 6 ++- guix/scripts/repl.scm | 5 +- guix/scripts/search.scm | 6 ++- guix/scripts/show.scm | 4 +- guix/scripts/size.scm | 7 ++- guix/scripts/substitute.scm | 7 ++- guix/scripts/system.scm | 4 +- guix/scripts/time-machine.scm | 4 +- guix/scripts/upgrade.scm | 6 ++- guix/scripts/weather.scm | 4 +- guix/ui.scm | 80 +++++++++++++++++++++++++++---- 38 files changed, 281 insertions(+), 63 deletions(-) diff --git a/guix/scripts.scm b/guix/scripts.scm index 8534948892..9792aaebe9 100644 --- a/guix/scripts.scm +++ b/guix/scripts.scm @@ -34,7 +34,12 @@ #:use-module (srfi srfi-19) #:use-module (srfi srfi-37) #:use-module (ice-9 match) - #:export (args-fold* + #:export (synopsis + category + define-command + %command-categories + + args-fold* parse-command-line maybe-build build-package @@ -50,6 +55,61 @@ ;;; ;;; Code: =20 +;; Syntactic keywords. +(define synopsis 'command-synopsis) +(define category 'command-category) + +(define-syntax define-command-categories + (syntax-rules (G_) + "Define command categories." + ((_ name assert-valid (identifiers (G_ synopses)) ...) + (begin + (define-public identifiers + ;; Define and export syntactic keywords. + (list 'syntactic-keyword-for-command-category)) + ... + + (define-syntax assert-valid + ;; Validate at expansion time that we're passed a valid category. + (syntax-rules (identifiers ...) + ((_ identifiers) #t) + ...)) + + (define name + ;; Alist mapping category name to synopsis. + `((identifiers . synopses) ...)))))) + +;; Command categories. +(define-command-categories %command-categories + assert-valid-command-category + (main (G_ "main commands")) + (development (G_ "software development commands")) + (packaging (G_ "packaging commands")) + (plumbing (G_ "plumbing commands")) + (internal (G_ "internal commands"))) + +(define-syntax define-command + (syntax-rules (category synopsis) + "Define the given command as a procedure along with its synopsis and, +optionally, its category. The synopsis becomes the docstring of the +procedure, but both the category and synopsis are meant to be read (parsed= ) by +'guix help'." + ;; The (synopsis ...) form is here so that xgettext sees those strings= as + ;; translatable. + ((_ (name . args) + (synopsis doc) body ...) + (define (name . args) + doc + body ...)) + ((_ (name . args) + (category cat) (synopsis doc) + body ...) + (begin + (assert-valid-command-category cat) + (define (name . args) + doc + body ...))))) + (define (args-fold* args options unrecognized-option-proc operand-proc . s= eeds) "A wrapper on top of `args-fold' that does proper user-facing error reporting." diff --git a/guix/scripts/archive.scm b/guix/scripts/archive.scm index f3b86fba14..02557ce454 100644 --- a/guix/scripts/archive.scm +++ b/guix/scripts/archive.scm @@ -355,7 +355,10 @@ output port." ;;; Entry point. ;;; =20 -(define (guix-archive . args) +(define-command (guix-archive . args) + (category plumbing) + (synopsis "manipulate, export, and import normalized archives (nars)") + (define (lines port) ;; Return lines read from PORT. (let loop ((line (read-line port)) diff --git a/guix/scripts/authenticate.scm b/guix/scripts/authenticate.scm index f1fd8ee895..a4b9171fc7 100644 --- a/guix/scripts/authenticate.scm +++ b/guix/scripts/authenticate.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright =C2=A9 2013, 2014, 2015, 2016, 2017 Ludovic Court=C3=A8s +;;; Copyright =C2=A9 2013, 2014, 2015, 2016, 2017, 2020 Ludovic Court=C3= =A8s ;;; ;;; This file is part of GNU Guix. ;;; @@ -18,6 +18,7 @@ =20 (define-module (guix scripts authenticate) #:use-module (guix config) + #:use-module (guix scripts) #:use-module (guix base16) #:use-module (gcrypt pk-crypto) #:use-module (guix pki) @@ -90,7 +91,10 @@ to stdout upon success." ;;; unmodified currently. ;;; =20 -(define (guix-authenticate . args) +(define-command (guix-authenticate . args) + (category internal) + (synopsis "sign or verify signatures on normalized archives (nars)") + ;; Signature sexps written to stdout may contain binary data, so force ;; ISO-8859-1 encoding so that things are not mangled. See ;; for details. diff --git a/guix/scripts/build.scm b/guix/scripts/build.scm index 6286a43c02..25418661b9 100644 --- a/guix/scripts/build.scm +++ b/guix/scripts/build.scm @@ -945,7 +945,10 @@ needed." ;;; Entry point. ;;; =20 -(define (guix-build . args) +(define-command (guix-build . args) + (category packaging) + (synopsis "build packages or derivations without installing them") + (define opts (parse-command-line args %options (list %default-options))) diff --git a/guix/scripts/challenge.scm b/guix/scripts/challenge.scm index 624f51b200..39bd2c1c0f 100644 --- a/guix/scripts/challenge.scm +++ b/guix/scripts/challenge.scm @@ -475,7 +475,10 @@ Challenge the substitutes for PACKAGE... provided by o= ne or more servers.\n")) ;;; Entry point. ;;; =20 -(define (guix-challenge . args) +(define-command (guix-challenge . args) + (category packaging) + (synopsis "challenge substitute servers, comparing their binaries") + (with-error-handling (let* ((opts (parse-command-line args %options (list %default-opti= ons) #:build-options? #f)) diff --git a/guix/scripts/container.scm b/guix/scripts/container.scm index 8041d64b6b..2369437043 100644 --- a/guix/scripts/container.scm +++ b/guix/scripts/container.scm @@ -20,6 +20,7 @@ (define-module (guix scripts container) #:use-module (ice-9 match) #:use-module (guix ui) + #:use-module (guix scripts) #:export (guix-container)) =20 (define (show-help) @@ -46,7 +47,10 @@ Build and manipulate Linux containers.\n")) (proc (string->symbol (string-append "guix-container-" name)))) (module-ref module proc))) =20 -(define (guix-container . args) +(define-command (guix-container . args) + (category development) + (synopsis "run code in containers created by 'guix environment -C'") + (with-error-handling (match args (() diff --git a/guix/scripts/copy.scm b/guix/scripts/copy.scm index 274620fc1e..2780d4fbe9 100644 --- a/guix/scripts/copy.scm +++ b/guix/scripts/copy.scm @@ -170,7 +170,10 @@ Copy ITEMS to or from the specified host over SSH.\n")) ;;; Entry point. ;;; =20 -(define (guix-copy . args) +(define-command (guix-copy . args) + (category plumbing) + (synopsis "copy store items remotely over SSH") + (with-error-handling (let* ((opts (parse-command-line args %options (list %default-opti= ons))) (source (assoc-ref opts 'source)) diff --git a/guix/scripts/deploy.scm b/guix/scripts/deploy.scm index 4a68197620..1b5be307be 100644 --- a/guix/scripts/deploy.scm +++ b/guix/scripts/deploy.scm @@ -136,7 +136,8 @@ Perform the deployment specified by FILE.\n")) (machine-display-name machine)))) =20 -(define (guix-deploy . args) +(define-command (guix-deploy . args) + (synopsis "deploy operating systems on a set of machines") (define (handle-argument arg result) (alist-cons 'file arg result)) =20 diff --git a/guix/scripts/describe.scm b/guix/scripts/describe.scm index bc868ffbbf..c3667516eb 100644 --- a/guix/scripts/describe.scm +++ b/guix/scripts/describe.scm @@ -304,7 +304,8 @@ text. The hyperlink links to a web view of COMMIT, whe= n available." ;;; Entry point. ;;; =20 -(define (guix-describe . args) +(define-command (guix-describe . args) + (synopsis "describe the channel revisions currently used") (let* ((opts (args-fold* args %options (lambda (opt name arg result) (leave (G_ "~A: unrecognized option~%") diff --git a/guix/scripts/download.scm b/guix/scripts/download.scm index 589f62da9d..ce8dd8b02c 100644 --- a/guix/scripts/download.scm +++ b/guix/scripts/download.scm @@ -156,7 +156,10 @@ and 'base16' ('hex' and 'hexadecimal' can be used as w= ell).\n")) ;;; Entry point. ;;; =20 -(define (guix-download . args) +(define-command (guix-download . args) + (category packaging) + (synopsis "download a file to the store and print its hash") + (define (parse-options) ;; Return the alist of option values. (args-fold* args %options diff --git a/guix/scripts/edit.scm b/guix/scripts/edit.scm index 43f3011869..49c9d945b6 100644 --- a/guix/scripts/edit.scm +++ b/guix/scripts/edit.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright =C2=A9 2015, 2016, 2019 Ludovic Court=C3=A8s +;;; Copyright =C2=A9 2015, 2016, 2019, 2020 Ludovic Court=C3=A8s ;;; Copyright =C2=A9 2015 Mathieu Lirzin ;;; Copyright =C2=A9 2020 Simon Tournier ;;; @@ -78,7 +78,10 @@ line." (search-path* %load-path (location-file location)))) =20 -(define (guix-edit . args) +(define-command (guix-edit . args) + (category packaging) + (synopsis "view and edit package definitions") + (define (parse-arguments) ;; Return the list of package names. (args-fold* args %options diff --git a/guix/scripts/environment.scm b/guix/scripts/environment.scm index 1fb3505307..ad50281eb2 100644 --- a/guix/scripts/environment.scm +++ b/guix/scripts/environment.scm @@ -678,7 +678,10 @@ message if any test fails." ;;; Entry point. ;;; =20 -(define (guix-environment . args) +(define-command (guix-environment . args) + (category development) + (synopsis "spawn one-off software environments") + (with-error-handling (let* ((opts (parse-args args)) (pure? (assoc-ref opts 'pure)) diff --git a/guix/scripts/gc.scm b/guix/scripts/gc.scm index ab7c13315f..043273f491 100644 --- a/guix/scripts/gc.scm +++ b/guix/scripts/gc.scm @@ -220,7 +220,9 @@ is deprecated; use '-D'~%")) ;;; Entry point. ;;; =20 -(define (guix-gc . args) +(define-command (guix-gc . args) + (synopsis "invoke the garbage collector") + (define (parse-options) ;; Return the alist of option values. (parse-command-line args %options (list %default-options) diff --git a/guix/scripts/git.scm b/guix/scripts/git.scm index bc829cbe99..4436d8a6e0 100644 --- a/guix/scripts/git.scm +++ b/guix/scripts/git.scm @@ -19,6 +19,7 @@ (define-module (guix scripts git) #:use-module (ice-9 match) #:use-module (guix ui) + #:use-module (guix scripts) #:export (guix-git)) =20 (define (show-help) @@ -45,7 +46,10 @@ Operate on Git repositories.\n")) (proc (string->symbol (string-append "guix-git-" name)))) (module-ref module proc))) =20 -(define (guix-git . args) +(define-command (guix-git . args) + (category plumbing) + (synopsis "operate on Git repositories") + (with-error-handling (match args (() diff --git a/guix/scripts/graph.scm b/guix/scripts/graph.scm index 73d9269de2..d7a08a4fe1 100644 --- a/guix/scripts/graph.scm +++ b/guix/scripts/graph.scm @@ -565,7 +565,10 @@ Emit a representation of the dependency graph of PACKA= GE...\n")) ;;; Entry point. ;;; =20 -(define (guix-graph . args) +(define-command (guix-graph . args) + (category packaging) + (synopsis "view and query package dependency graphs") + (with-error-handling (define opts (parse-command-line args %options diff --git a/guix/scripts/hash.scm b/guix/scripts/hash.scm index 9b4f419a24..797b99f053 100644 --- a/guix/scripts/hash.scm +++ b/guix/scripts/hash.scm @@ -116,7 +116,10 @@ and 'base16' ('hex' and 'hexadecimal' can be used as w= ell).\n")) ;;; Entry point. ;;; =20 -(define (guix-hash . args) +(define-command (guix-hash . args) + (category packaging) + (synopsis "compute the cryptographic hash of a file") + (define (parse-options) ;; Return the alist of option values. (parse-command-line args %options (list %default-options) diff --git a/guix/scripts/import.scm b/guix/scripts/import.scm index c6cc93fad8..0a3863f965 100644 --- a/guix/scripts/import.scm +++ b/guix/scripts/import.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright =C2=A9 2012, 2013, 2014 Ludovic Court=C3=A8s +;;; Copyright =C2=A9 2012, 2013, 2014, 2020 Ludovic Court=C3=A8s ;;; Copyright =C2=A9 2014 David Thompson ;;; Copyright =C2=A9 2018 Kyle Meyer ;;; Copyright =C2=A9 2019 Ricardo Wurmus @@ -21,6 +21,7 @@ =20 (define-module (guix scripts import) #:use-module (guix ui) + #:use-module (guix scripts) #:use-module (guix utils) #:use-module (srfi srfi-1) #:use-module (srfi srfi-11) @@ -98,7 +99,10 @@ Run IMPORTER with ARGS.\n")) (newline) (show-bug-report-information)) =20 -(define (guix-import . args) +(define-command (guix-import . args) + (category packaging) + (synopsis "import a package definition from an external repository") + (match args (() (format (current-error-port) diff --git a/guix/scripts/install.scm b/guix/scripts/install.scm index d88e86e77a..894e60f9da 100644 --- a/guix/scripts/install.scm +++ b/guix/scripts/install.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright =C2=A9 2019 Ludovic Court=C3=A8s +;;; Copyright =C2=A9 2019, 2020 Ludovic Court=C3=A8s ;;; ;;; This file is part of GNU Guix. ;;; @@ -66,7 +66,9 @@ This is an alias for 'guix package -i'.\n")) %transformation-options %standard-build-options))) =20 -(define (guix-install . args) +(define-command (guix-install . args) + (synopsis "install packages") + (define (handle-argument arg result arg-handler) ;; Treat all non-option arguments as package specs. (values (alist-cons 'install arg result) diff --git a/guix/scripts/lint.scm b/guix/scripts/lint.scm index 5168a1ca17..979d4f8363 100644 --- a/guix/scripts/lint.scm +++ b/guix/scripts/lint.scm @@ -157,7 +157,10 @@ run the checkers on all packages.\n")) ;;; Entry Point ;;; =20 -(define (guix-lint . args) +(define-command (guix-lint . args) + (category packaging) + (synopsis "validate package definitions") + (define (parse-options) ;; Return the alist of option values. (parse-command-line args %options (list %default-options) diff --git a/guix/scripts/offload.scm b/guix/scripts/offload.scm index 1e0e9d7905..3dc8ccefcb 100644 --- a/guix/scripts/offload.scm +++ b/guix/scripts/offload.scm @@ -39,6 +39,7 @@ #:select (fcntl-flock set-thread-name)) #:use-module ((guix build utils) #:select (which mkdir-p)) #:use-module (guix ui) + #:use-module (guix scripts) #:use-module (guix diagnostics) #:use-module (srfi srfi-1) #:use-module (srfi srfi-11) @@ -725,7 +726,10 @@ machine." ;;; Entry point. ;;; =20 -(define (guix-offload . args) +(define-command (guix-offload . args) + (category plumbing) + (synopsis "set up and operate build offloading") + (define request-line-rx ;; The request format. See 'tryBuildHook' method in build.cc. (make-regexp "([01]) ([a-z0-9_-]+) (/[[:graph:]]+.drv) ([[:graph:]]*)"= )) diff --git a/guix/scripts/pack.scm b/guix/scripts/pack.scm index 9d6881fdaf..379e6a3ac6 100644 --- a/guix/scripts/pack.scm +++ b/guix/scripts/pack.scm @@ -1089,7 +1089,10 @@ Create a bundle of PACKAGE.\n")) ;;; Entry point. ;;; =20 -(define (guix-pack . args) +(define-command (guix-pack . args) + (category development) + (synopsis "create application bundles") + (define opts (parse-command-line args %options (list %default-options))) =20 diff --git a/guix/scripts/package.scm b/guix/scripts/package.scm index ac8dedb5f3..4eb968a49b 100644 --- a/guix/scripts/package.scm +++ b/guix/scripts/package.scm @@ -941,7 +941,9 @@ processed, #f otherwise." ;;; Entry point. ;;; =20 -(define (guix-package . args) +(define-command (guix-package . args) + (synopsis "manage packages and profiles") + (define (handle-argument arg result arg-handler) ;; Process non-option argument ARG by calling back ARG-HANDLER. (if arg-handler diff --git a/guix/scripts/perform-download.scm b/guix/scripts/perform-downl= oad.scm index df787a9940..8d409092ba 100644 --- a/guix/scripts/perform-download.scm +++ b/guix/scripts/perform-download.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright =C2=A9 2016, 2017, 2018 Ludovic Court=C3=A8s +;;; Copyright =C2=A9 2016, 2017, 2018, 2020 Ludovic Court=C3=A8s ;;; ;;; This file is part of GNU Guix. ;;; @@ -18,6 +18,7 @@ =20 (define-module (guix scripts perform-download) #:use-module (guix ui) + #:use-module (guix scripts) #:use-module (guix derivations) #:use-module ((guix store) #:select (derivation-path? store-path?)) #:use-module (guix build download) @@ -91,14 +92,15 @@ actual output is different from that when we're doing a= 'bmCheck' or (leave (G_ "refusing to run with elevated privileges (UID ~a)~%") (getuid)))) =20 -(define (guix-perform-download . args) - "Perform the download described by the given fixed-output derivation. +(define-command (guix-perform-download . args) + (category internal) + (synopsis "perform download described by fixed-output derivations") =20 -This is an \"out-of-band\" download in that this code is executed directly= by -the daemon and not explicitly described as an input of the derivation. Th= is -allows us to sidestep bootstrapping problems, such downloading the source = code -of GnuTLS over HTTPS, before we have built GnuTLS. See -." + ;; This is an "out-of-band" download in that this code is executed direc= tly + ;; by the daemon and not explicitly described as an input of the derivat= ion. + ;; This allows us to sidestep bootstrapping problems, such as downloading + ;; the source code of GnuTLS over HTTPS before we have built GnuTLS. See + ;; . =20 (define print-build-trace? (match (getenv "_NIX_OPTIONS") diff --git a/guix/scripts/processes.scm b/guix/scripts/processes.scm index 35698a0216..b4ca7b1687 100644 --- a/guix/scripts/processes.scm +++ b/guix/scripts/processes.scm @@ -223,7 +223,9 @@ List the current Guix sessions and their processes.")) ;;; Entry point. ;;; =20 -(define (guix-processes . args) +(define-command (guix-processes . args) + (category plumbing) + (synopsis "list currently running sessions") (define options (args-fold* args %options (lambda (opt name arg result) diff --git a/guix/scripts/publish.scm b/guix/scripts/publish.scm index 61542f83a0..4eaf961ab2 100644 --- a/guix/scripts/publish.scm +++ b/guix/scripts/publish.scm @@ -1013,7 +1013,10 @@ methods, return the applicable compression." ;;; Entry point. ;;; =20 -(define (guix-publish . args) +(define-command (guix-publish . args) + (category packaging) + (synopsis "publish build results over HTTP") + (with-error-handling (let* ((opts (args-fold* args %options (lambda (opt name arg result) diff --git a/guix/scripts/pull.scm b/guix/scripts/pull.scm index 3b980b8f3f..bb1b560a22 100644 --- a/guix/scripts/pull.scm +++ b/guix/scripts/pull.scm @@ -751,7 +751,9 @@ Use '~/.config/guix/channels.scm' instead.")) channels))) =20 -(define (guix-pull . args) +(define-command (guix-pull . args) + (synopsis "pull the latest revision of Guix") + (with-error-handling (with-git-error-handling (let* ((opts (parse-command-line args %options diff --git a/guix/scripts/refresh.scm b/guix/scripts/refresh.scm index efada1df5a..4a71df28d1 100644 --- a/guix/scripts/refresh.scm +++ b/guix/scripts/refresh.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright =C2=A9 2013, 2014, 2015, 2016, 2017, 2018, 2019 Ludovic Cour= t=C3=A8s +;;; Copyright =C2=A9 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 Ludovi= c Court=C3=A8s ;;; Copyright =C2=A9 2013 Nikita Karetnikov ;;; Copyright =C2=A9 2014 Eric Bavier ;;; Copyright =C2=A9 2015 Alex Kost @@ -496,7 +496,10 @@ all are dependent packages: ~{~a~^ ~}~%") ;;; Entry point. ;;; =20 -(define (guix-refresh . args) +(define-command (guix-refresh . args) + (category packaging) + (synopsis "update existing package definitions") + (define (parse-options) ;; Return the alist of option values. (parse-command-line args %options (list %default-options) diff --git a/guix/scripts/remove.scm b/guix/scripts/remove.scm index 2f06ea4f37..a46ad04d56 100644 --- a/guix/scripts/remove.scm +++ b/guix/scripts/remove.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright =C2=A9 2019 Ludovic Court=C3=A8s +;;; Copyright =C2=A9 2019, 2020 Ludovic Court=C3=A8s ;;; ;;; This file is part of GNU Guix. ;;; @@ -63,7 +63,9 @@ This is an alias for 'guix package -r'.\n")) =20 %standard-build-options))) =20 -(define (guix-remove . args) +(define-command (guix-remove . args) + (synopsis "remove installed packages") + (define (handle-argument arg result arg-handler) ;; Treat all non-option arguments as package specs. (values (alist-cons 'remove arg result) diff --git a/guix/scripts/repl.scm b/guix/scripts/repl.scm index 0ea9c3655c..3c79e89f8d 100644 --- a/guix/scripts/repl.scm +++ b/guix/scripts/repl.scm @@ -137,7 +137,10 @@ call THUNK." (loop))))))) =20 -(define (guix-repl . args) +(define-command (guix-repl . args) + (category plumbing) + (synopsis "read-eval-print loop (REPL) for interactive programming") + (define opts (args-fold* args %options (lambda (opt name arg result) diff --git a/guix/scripts/search.scm b/guix/scripts/search.scm index 827b2eb7a9..0c9e6af07b 100644 --- a/guix/scripts/search.scm +++ b/guix/scripts/search.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright =C2=A9 2019 Ludovic Court=C3=A8s +;;; Copyright =C2=A9 2019, 2020 Ludovic Court=C3=A8s ;;; ;;; This file is part of GNU Guix. ;;; @@ -57,7 +57,9 @@ This is an alias for 'guix package -s'.\n")) (member "load-path" (option-names option))) %standard-build-options))) =20 -(define (guix-search . args) +(define-command (guix-search . args) + (synopsis "search for packages") + (define (handle-argument arg result) ;; Treat all non-option arguments as regexps. (cons `(query search ,(or arg "")) diff --git a/guix/scripts/show.scm b/guix/scripts/show.scm index a2b0030a63..535d03c1a6 100644 --- a/guix/scripts/show.scm +++ b/guix/scripts/show.scm @@ -57,7 +57,9 @@ This is an alias for 'guix package --show=3D'.\n")) (member "load-path" (option-names option))) %standard-build-options))) =20 -(define (guix-show . args) +(define-command (guix-show . args) + (synopsis "show information about packages") + (define (handle-argument arg result) ;; Treat all non-option arguments as regexps. (cons `(query show ,arg) diff --git a/guix/scripts/size.scm b/guix/scripts/size.scm index c42f4f7782..e46983382a 100644 --- a/guix/scripts/size.scm +++ b/guix/scripts/size.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright =C2=A9 2015, 2016, 2017, 2018, 2019 Ludovic Court=C3=A8s +;;; Copyright =C2=A9 2015, 2016, 2017, 2018, 2019, 2020 Ludovic Court=C3= =A8s ;;; Copyright =C2=A9 2019 Simon Tournier ;;; ;;; This file is part of GNU Guix. @@ -298,7 +298,10 @@ Report the size of the PACKAGE or STORE-ITEM, with its= dependencies.\n")) ;;; Entry point. ;;; =20 -(define (guix-size . args) +(define-command (guix-size . args) + (category packaging) + (synopsis "profile the on-disk size of packages") + (with-error-handling (let* ((opts (parse-command-line args %options (list %default-opti= ons) #:build-options? #f)) diff --git a/guix/scripts/substitute.scm b/guix/scripts/substitute.scm index f9d19fd735..1462ce9918 100755 --- a/guix/scripts/substitute.scm +++ b/guix/scripts/substitute.scm @@ -20,6 +20,7 @@ =20 (define-module (guix scripts substitute) #:use-module (guix ui) + #:use-module (guix scripts) #:use-module (guix store) #:use-module (guix utils) #:use-module (guix combinators) @@ -1095,8 +1096,10 @@ default value." (unless (string->uri uri) (leave (G_ "~a: invalid URI~%") uri))) =20 -(define (guix-substitute . args) - "Implement the build daemon's substituter protocol." +(define-command (guix-substitute . args) + (category internal) + (synopsis "implement the build daemon's substituter protocol") + (define print-build-trace? (match (or (find-daemon-option "untrusted-print-extended-build-trace") (find-daemon-option "print-extended-build-trace")) diff --git a/guix/scripts/system.scm b/guix/scripts/system.scm index 3222a53c8f..2a514166eb 100644 --- a/guix/scripts/system.scm +++ b/guix/scripts/system.scm @@ -1240,7 +1240,9 @@ argument list and OPTS is the option alist." ;; need an operating system configuration file. (else (process-action command args opts)))) =20 -(define (guix-system . args) +(define-command (guix-system . args) + (synopsis "build and deploy full operating systems") + (define (parse-sub-command arg result) ;; Parse sub-command ARG and augment RESULT accordingly. (if (assoc-ref result 'action) diff --git a/guix/scripts/time-machine.scm b/guix/scripts/time-machine.scm index 441673b780..0d27414702 100644 --- a/guix/scripts/time-machine.scm +++ b/guix/scripts/time-machine.scm @@ -128,7 +128,9 @@ Execute COMMAND ARGS... in an older version of Guix.\n"= )) ;;; Entry point. ;;; =20 -(define (guix-time-machine . args) +(define-command (guix-time-machine . args) + (synopsis "run commands from a different revision") + (with-error-handling (with-git-error-handling (let* ((opts (parse-args args)) diff --git a/guix/scripts/upgrade.scm b/guix/scripts/upgrade.scm index d2784669be..8c7abd133a 100644 --- a/guix/scripts/upgrade.scm +++ b/guix/scripts/upgrade.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright =C2=A9 2019 Ludovic Court=C3=A8s +;;; Copyright =C2=A9 2019, 2020 Ludovic Court=C3=A8s ;;; Copyright =C2=A9 2020 Jakub K=C4=85dzio=C5=82ka ;;; ;;; This file is part of GNU Guix. @@ -67,7 +67,9 @@ This is an alias for 'guix package -u'.\n")) %transformation-options %standard-build-options))) =20 -(define (guix-upgrade . args) +(define-command (guix-upgrade . args) + (synopsis "upgrade packages to their latest version") + (define (handle-argument arg result arg-handler) ;; Accept at most one non-option argument, and treat it as an upgrade ;; regexp. diff --git a/guix/scripts/weather.scm b/guix/scripts/weather.scm index 3035ff6ca8..6a2582c997 100644 --- a/guix/scripts/weather.scm +++ b/guix/scripts/weather.scm @@ -495,7 +495,9 @@ SERVER. Display information for packages with at least= THRESHOLD dependents." ;;; Entry point. ;;; =20 -(define (guix-weather . args) +(define-command (guix-weather . args) + (synopsis "report on the availability of pre-built package binaries") + (define (package-list opts) ;; Return the package list specified by OPTS. (let ((files (filter-map (match-lambda diff --git a/guix/ui.scm b/guix/ui.scm index 981e133aaf..51a61be687 100644 --- a/guix/ui.scm +++ b/guix/ui.scm @@ -60,6 +60,7 @@ ;; Avoid "overrides core binding" warning. delete)) #:use-module (srfi srfi-1) + #:use-module (srfi srfi-9 gnu) #:use-module (srfi srfi-11) #:use-module (srfi srfi-19) #:use-module (srfi srfi-26) @@ -1989,6 +1990,44 @@ optionally contain a version number and an output na= me, as in these examples: (G_ "Try `guix --help' for more information.~%")) (exit 1)) =20 +;; Representation of a 'guix' command. +(define-immutable-record-type + (command name synopsis category) + command? + (name command-name) + (synopsis command-synopsis) + (category command-category)) + +(define (source-file-command file) + "Read FILE, a Scheme source file, and return either a object b= ased +on the 'define-command' top-level form found therein, or #f if FILE does n= ot +contain a 'define-command' form." + (define command-name + (match (string-split file #\/) + ((_ ... "guix" "scripts" name) + (list (file-sans-extension name))) + ((_ ... "guix" "scripts" first second) + (list first (file-sans-extension second))))) + + ;; The strategy here is to parse FILE. This is much cheaper than a + ;; technique based on run-time introspection where we'd load FILE and all + ;; the modules it depends on. + (call-with-input-file file + (lambda (port) + (let loop () + (match (read port) + (('define-command _ ('synopsis synopsis) + _ ...) + (command command-name synopsis 'main)) + (('define-command _ + ('category category) ('synopsis synopsis) + _ ...) + (command command-name synopsis category)) + ((? eof-object?) + #f) + (_ + (loop))))))) + (define (command-files) "Return the list of source files that define Guix sub-commands." (define directory @@ -2000,28 +2039,51 @@ optionally contain a version number and an output n= ame, as in these examples: (cut string-suffix? ".scm" <>)) =20 (if directory - (scandir directory dot-scm?) + (map (cut string-append directory "/" <>) + (scandir directory dot-scm?)) '())) =20 (define (commands) - "Return the list of Guix command names." - (map (compose (cut string-drop-right <> 4) - basename) - (command-files))) + "Return the list of commands, alphabetically sorted." + (filter-map source-file-command (command-files))) =20 (define (show-guix-help) (define (internal? command) (member command '("substitute" "authenticate" "offload" "perform-download"))) =20 + (define (display-commands commands) + (let* ((names (map (lambda (command) + (string-join (command-name command))) + commands)) + (max-width (reduce max 0 (map string-length names)))) + (for-each (lambda (name command) + (format #t " ~a ~a~%" + (string-pad-right name max-width) + (G_ (command-synopsis command)))) + names + commands))) + + (define (category-predicate category) + (lambda (command) + (eq? category (command-category command)))) + (format #t (G_ "Usage: guix COMMAND ARGS... Run COMMAND with ARGS.\n")) (newline) (format #t (G_ "COMMAND must be one of the sub-commands listed below:\n"= )) - (newline) - ;; TODO: Display a synopsis of each command. - (format #t "~{ ~a~%~}" (sort (remove internal? (commands)) - stringFrom b3494f3cd670e0d1e5842b9b022c2606a520d34a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= Date: Tue, 1 Sep 2020 22:23:50 +0200 Subject: [PATCH 1/2] ui: '--help' output links to . * guix/ui.scm (show-bug-report-information): Link to instead of . The former is much more useful and includes links to GNU manuals. --- guix/ui.scm | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/guix/ui.scm b/guix/ui.scm index efc3f39186..981e133aaf 100644 --- a/guix/ui.scm +++ b/guix/ui.scm @@ -541,8 +541,9 @@ There is NO WARRANTY, to the extent permitted by law. Report bugs to: ~a.") %guix-bug-report-address) (format #t (G_ " ~a home page: <~a>") %guix-package-name %guix-home-page-url) - (display (G_ " -General help using GNU software: ")) + (format #t (G_ " +General help using Guix and GNU software: <~a>") + "https://guix.gnu.org/help/") (newline)) (define (augmented-system-error-handler file) -- 2.28.0 --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Mon Sep 07 08:58:45 2020 Received: (at 43159) by debbugs.gnu.org; 7 Sep 2020 12:58:45 +0000 Received: from localhost ([127.0.0.1]:48385 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kFGjM-0007aM-0K for submit@debbugs.gnu.org; Mon, 07 Sep 2020 08:58:44 -0400 Received: from eggs.gnu.org ([209.51.188.92]:46278) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kFGjG-0007a4-S7 for 43159@debbugs.gnu.org; Mon, 07 Sep 2020 08:58:40 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:41855) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kFGjB-0004qY-I4; Mon, 07 Sep 2020 08:58:33 -0400 Received: from [2001:660:6102:320:e120:2c8f:8909:cdfe] (port=44070 helo=ribbon) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kFGjA-0002Ik-Lj; Mon, 07 Sep 2020 08:58:33 -0400 From: =?utf-8?Q?Ludovic_Court=C3=A8s?= To: zimoun Subject: Re: [bug#43159] [PATCH 0/2] Make 'guix help' helpful References: <20200901203520.21103-1-ludo@gnu.org> Date: Mon, 07 Sep 2020 14:58:27 +0200 In-Reply-To: (zimoun's message of "Thu, 3 Sep 2020 18:40:41 +0200") Message-ID: <87o8mhiw0c.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 43159 Cc: 43159@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Hi, zimoun skribis: >> environment spawn one-off software environments > > spawn one-off? =E2=80=9COne-off=E2=80=9D is used as an adjective to mean a software enviro= nment that is used once and then thrown away. Per WordNet: --8<---------------cut here---------------start------------->8--- Overview of noun one-off The noun one-off has 1 sense (no senses from tagged texts) =20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20= =20=20=20=20=20=20=20=20=20=20=20=20=20=20 1. one-off -- (a happening that occurs only once and is not repeated) --8<---------------cut here---------------end--------------->8--- Thanks for your suggestions! Ludo=E2=80=99. From debbugs-submit-bounces@debbugs.gnu.org Thu Sep 10 06:35:02 2020 Received: (at 43159-done) by debbugs.gnu.org; 10 Sep 2020 10:35:02 +0000 Received: from localhost ([127.0.0.1]:37278 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kGJuv-0002Rs-Uw for submit@debbugs.gnu.org; Thu, 10 Sep 2020 06:35:02 -0400 Received: from eggs.gnu.org ([209.51.188.92]:41278) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kGJut-0002RU-S3 for 43159-done@debbugs.gnu.org; Thu, 10 Sep 2020 06:35:00 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:55793) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kGJuo-0003MK-Ja; Thu, 10 Sep 2020 06:34:54 -0400 Received: from [2001:660:6102:320:e120:2c8f:8909:cdfe] (port=43144 helo=ribbon) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kGJun-0006Va-RI; Thu, 10 Sep 2020 06:34:54 -0400 From: =?utf-8?Q?Ludovic_Court=C3=A8s?= To: Maxim Cournoyer Subject: Re: [bug#43159] [PATCHES v2] scripts: Use 'define-command' and have 'guix help' use that. References: <20200901203520.21103-1-ludo@gnu.org> <20200901204136.21375-1-ludo@gnu.org> <87r1rk595p.fsf@gmail.com> <87tuw9iw34.fsf_-_@gnu.org> Date: Thu, 10 Sep 2020 12:34:46 +0200 In-Reply-To: <87tuw9iw34.fsf_-_@gnu.org> ("Ludovic \=\?utf-8\?Q\?Court\=C3\=A8s\?\= \=\?utf-8\?Q\?\=22's\?\= message of "Mon, 07 Sep 2020 14:56:47 +0200") Message-ID: <874ko5hqd5.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 43159-done Cc: 43159-done@debbugs.gnu.org, Efraim Flashner , zimoun X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Ludovic Court=C3=A8s skribis: > Here=E2=80=99s a v2 of the patches, where I tried to take your feedback i= nto > account. Changes: > > =E2=80=A2 Categories that appear in uses of =E2=80=98define-command=E2= =80=99 are now validated > at macro-expansion time. > > =E2=80=A2 (guix scripts) contains an alist of the known categories and > =E2=80=98show-help=E2=80=99 traverses it. > > =E2=80=A2 Changed the label for development commands to =E2=80=9Ccomman= ds for > development=E2=80=9D, and changed =E2=80=9Cadvanced=E2=80=9D to =E2= =80=9Cplumbing=E2=80=9D. > > =E2=80=A2 Added a =E2=80=9Cpackaging=E2=80=9D category. > > =E2=80=A2 Fixed the typos you reported. I pushed this v2 as 3794ce93be8216d8378df7b808ce7f53b1e05a53. Let=E2=80=99s iterate from here if people have ideas about better categoriz= ation or things like that. Thanks, Ludo=E2=80=99. From debbugs-submit-bounces@debbugs.gnu.org Thu Sep 10 06:54:04 2020 Received: (at submit) by debbugs.gnu.org; 10 Sep 2020 10:54:04 +0000 Received: from localhost ([127.0.0.1]:37314 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kGKDL-00053Z-OK for submit@debbugs.gnu.org; Thu, 10 Sep 2020 06:54:04 -0400 Received: from lists.gnu.org ([209.51.188.17]:60260) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kGKDI-000538-9b for submit@debbugs.gnu.org; Thu, 10 Sep 2020 06:54:01 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:55642) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kGKDH-0002aK-U6 for guix-patches@gnu.org; Thu, 10 Sep 2020 06:54:00 -0400 Received: from sender4-of-o51.zoho.com ([136.143.188.51]:21109) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kGKDF-0005sp-ER; Thu, 10 Sep 2020 06:53:59 -0400 ARC-Seal: i=1; a=rsa-sha256; t=1599735233; cv=none; d=zohomail.com; s=zohoarc; b=Ljjgsl06sbej7ZxLrKEsc11yRWtE7RfEfWE7LuzSNpo6z0+oJhWRagiO9yp9E2ElQARZ6WbPQdDvO47W7PJO3a7y7CEWLp463h6AaaJtPdHIqSGerCNLhbtbKtncqyxNjin6tLb5Lfpgxhk7TqiHfBVLeMNQeiJTVvDUSbkJi6A= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1599735233; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:MIME-Version:Message-ID:References:Subject:To; bh=pxMe05DcpXgpcjWbpq6PchA1mGjl6lN6aPNIEYL15lg=; b=jTyfytdZOkT9NI86wMO/mOkdRMSeKBCoIBn8qaaQgqMayAVORvEJSYTuInJJXnqnqI2kWy2nS4dL35rVjQxDPWQveaD/IreGbYXlXbJWuSDQe1BjtPm/ide8l50CckUyQpLD/SFj/Dq2dP7Cl8EI4V/QQUWakbfdPM6GYHMFd9U= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass header.i=elephly.net; spf=pass smtp.mailfrom=rekado@elephly.net; dmarc=pass header.from= header.from= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1599735233; s=zoho; d=elephly.net; i=rekado@elephly.net; h=References:From:To:Cc:Subject:In-reply-to:Date:Message-ID:MIME-Version:Content-Type:Content-Transfer-Encoding; bh=pxMe05DcpXgpcjWbpq6PchA1mGjl6lN6aPNIEYL15lg=; b=BDci1STs9JW5S7njs5P/cIToS7Iym7oTQQhWrvOrFzljA6J7wdzZ2INo8Fzym/4i RUU06nA7W4I8EiT0BfPUGeAGECouGZWKir2HrtLL8HinYKnO/2lRyWqNh0dUrzP08Cr N+9HGSFrCx1QaNLnxsUaPYKNvOgz1E3N4U18CpfA= Received: from localhost (p54ad4af6.dip0.t-ipconnect.de [84.173.74.246]) by mx.zohomail.com with SMTPS id 1599735231122711.0382652229035; Thu, 10 Sep 2020 03:53:51 -0700 (PDT) References: <20200901203520.21103-1-ludo@gnu.org> <20200901204136.21375-1-ludo@gnu.org> <87r1rk595p.fsf@gmail.com> <87tuw9iw34.fsf_-_@gnu.org> <874ko5hqd5.fsf@gnu.org> User-agent: mu4e 1.4.13; emacs 27.1 From: Ricardo Wurmus To: Ludovic =?utf-8?Q?Court=C3=A8s?= Subject: Re: bug#43159: [PATCHES v2] scripts: Use 'define-command' and have 'guix help' use that. In-reply-to: <874ko5hqd5.fsf@gnu.org> X-URL: https://elephly.net X-PGP-Key: https://elephly.net/rekado.pubkey X-PGP-Fingerprint: BCA6 89B6 3655 3801 C3C6 2150 197A 5888 235F ACAC Date: Thu, 10 Sep 2020 12:55:04 +0200 Message-ID: <87h7s56gvr.fsf@elephly.net> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-ZohoMailClient: External Received-SPF: pass client-ip=136.143.188.51; envelope-from=rekado@elephly.net; helo=sender4-of-o51.zoho.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/10 06:37:33 X-ACL-Warn: Detected OS = Linux 3.11 and newer [fuzzy] X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: -1.3 (-) X-Debbugs-Envelope-To: submit Cc: guix-patches@gnu.org, zimoun , Efraim Flashner , Maxim Cournoyer , 43159-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.3 (--) I=E2=80=99m a bit late, but I=E2=80=99m very happy to see that =E2=80=9Cfor= developers=E2=80=9D has become =E2=80=9Cfor development=E2=80=9D! Ludovic Court=C3=A8s writes: > Ludovic Court=C3=A8s skribis: > >> Here=E2=80=99s a v2 of the patches, where I tried to take your feedback = into >> account. Changes: >> >> =E2=80=A2 Categories that appear in uses of =E2=80=98define-command=E2= =80=99 are now validated >> at macro-expansion time. Neat! >> =E2=80=A2 (guix scripts) contains an alist of the known categories and >> =E2=80=98show-help=E2=80=99 traverses it. Knowing that guile-config exists for automatically generating help screens, configuration files, command line options, and all that I wonder if there=E2=80=99s anything here that could become part of guile-con= fig and move out of Guix. I had been in that situation myself where I felt that guile-config may not be a great fit for my help texts because of minor quibbles about the format or the way things are presented by default. In the end I decided to use guile-config, because I prefer to have this handled by someone else who keeps thinking about the problems relating to argument parsing, configuration files, and help texts. It may not be a great fit for Guix now, but I wonder if it could. In the long run I think it would be good for Guix to become a little less special =E2=80=94 no matter if that=E2=80=99s monad macros, records, argpar= sing, or configuration files. This is not a recommendation either way. I just wonder if in the long term we could benefit from moving all this to a separate package. >> =E2=80=A2 Changed the label for development commands to =E2=80=9Ccomma= nds for >> development=E2=80=9D, and changed =E2=80=9Cadvanced=E2=80=9D to =E2= =80=9Cplumbing=E2=80=9D. >> >> =E2=80=A2 Added a =E2=80=9Cpackaging=E2=80=9D category. >> >> =E2=80=A2 Fixed the typos you reported. > > I pushed this v2 as 3794ce93be8216d8378df7b808ce7f53b1e05a53. Excellent! Thank you! --=20 Ricardo From debbugs-submit-bounces@debbugs.gnu.org Fri Sep 11 14:57:47 2020 Received: (at 43159) by debbugs.gnu.org; 11 Sep 2020 18:57:48 +0000 Received: from localhost ([127.0.0.1]:45523 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kGoF1-0006Ye-Jd for submit@debbugs.gnu.org; Fri, 11 Sep 2020 14:57:47 -0400 Received: from mail-qt1-f195.google.com ([209.85.160.195]:40526) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kGoEz-0006YR-2E for 43159@debbugs.gnu.org; Fri, 11 Sep 2020 14:57:46 -0400 Received: by mail-qt1-f195.google.com with SMTP id v54so8694432qtj.7 for <43159@debbugs.gnu.org>; Fri, 11 Sep 2020 11:57:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-transfer-encoding; bh=S98b0C0qLfxzZuupt2I0hCvXelK9OimQ31WdE/x/SQM=; b=fEoFEZ/r7q4N//ragKM4+eVEhIFyNRrxneQglbr3so6vCwhojq5f8uYUA2vEPQeBuQ xHyb1EHc0S8Wq9qMufA6hrsPlSB95VOQ+YAhpLfB1PzdSfjBCBsaKjk7Au45dJDvtgc4 o52ilGWO7Ctwbr9Mztc0lR40k1gUbbp6E/qFaeY/kkH/WkBgDros0VVQvA5jyCXTwnwq UfT/loG0zSq6qTqIwSm5saFIS/jZtm7q95KqN1vJ5rU53l5/NlNPPFa2S15wi3/vOZ5a pgdScM7BR6IB0SjfmMfifrCVfpMbSEIb8agqRng4vw/CsEZVUrEA/quf+aC7Ymv2mO7e ctMg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version:content-transfer-encoding; bh=S98b0C0qLfxzZuupt2I0hCvXelK9OimQ31WdE/x/SQM=; b=ooao0+Cy4u1n5G0YxaMblf8fQX6xBHruWr7+CsvbfdKI0aq9IAK3kBiuFJZtiXch2d mxiW95ND2sWT/BmpkGMC9D/0zA3q7klAX1qhpC1LdZbBFvbtKNgHfgcWTm/RzXBuy4TX rWQxQCmJ5TTVgisjtqECwMgd71QbqoS7R1NqVlRAidFEnlBfdDdZ+qvpnAoniwmyGPUY t/Ek9Ulo6CPGgp7s0xTXEIJqVV30oYJY+UZPPfTj1CmmZMpUSPUorF0Ow6OxngKmG0QK 4Mlhn6WXNwHREyE+vuvfKTVknW0bh41w13OvBRoVostwNzeS7CmQIMDvwgt8uuyjb7Tz VIhw== X-Gm-Message-State: AOAM533ORdCi8kIAJWqYcR0kNbF90WtbFXmUGl9FdacnsVplpiYtpi5h hsNvXUZTPhtNByNZeicGX+P5XQdResS6zw== X-Google-Smtp-Source: ABdhPJyEPD/h0vAXrBYCmZKwPxbmFYjCivR0vMznXE2WG+AjBFad6zKMd/UUaV8etB4aqTXukgboBg== X-Received: by 2002:ac8:35dd:: with SMTP id l29mr3274554qtb.94.1599850659169; Fri, 11 Sep 2020 11:57:39 -0700 (PDT) Received: from hurd (dsl-10-146-200.b2b2c.ca. [72.10.146.200]) by smtp.gmail.com with ESMTPSA id w59sm3837440qtd.1.2020.09.11.11.57.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 11 Sep 2020 11:57:38 -0700 (PDT) From: Maxim Cournoyer To: Ludovic =?utf-8?Q?Court=C3=A8s?= Subject: Re: [bug#43159] [PATCH 1/2] scripts: Use 'define-command' and have 'guix help' use that. References: <20200901203520.21103-1-ludo@gnu.org> <20200901204136.21375-1-ludo@gnu.org> <87r1rk595p.fsf@gmail.com> <87blinx9ii.fsf@gnu.org> Date: Fri, 11 Sep 2020 14:58:19 -0400 In-Reply-To: <87blinx9ii.fsf@gnu.org> ("Ludovic =?utf-8?Q?Court=C3=A8s=22'?= =?utf-8?Q?s?= message of "Thu, 03 Sep 2020 15:41:41 +0200") Message-ID: <878sdg6sz8.fsf@gmail.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 43159 Cc: 43159@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Hi Ludovic, Sorry I couldn't reply faster. Ludovic Court=C3=A8s writes: [...] >>> +;; Syntactic keywords. >>> +(define synopsis 'command-synopsis) >>> +(define category 'command-category) >> >> Are these definition really necessary/useful? I would have thought >> having category and synopsis understood as literals in the >> define-command syntax was enough? > > It=E2=80=99s not strictly necessary but it=E2=80=99s been considered =E2= =80=9Cgood practice=E2=80=9D. > That allows users to detect name clashes, to rename/hide/etc. syntactic > keywords and so on. I see! Thank you for explaining. [...] >>> + ;; The strategy here is to parse FILE. This is much cheaper than a >>> + ;; technique based on run-time introspection where we'd load FILE an= d all >>> + ;; the modules it depends on. >> >> Interesting! Have you measure it? I would have thought loading a couple >> optimized byte code modules could have been nearly as fast as parsing >> files manually. If so, I think it'd be preferable to use introspection >> rather than implement a custom parser. > > On a fast recent laptop with an SSD, a load of 0, hot cache, etc., we=E2= =80=99d > still be below 1s. But see: > > $ strace -c guix help >/dev/null > % time seconds usecs/call calls errors syscall > ------ ----------- ----------- --------- --------- ------------------ > 62.69 0.002698 1 2266 2043 stat > 10.94 0.000471 2 161 2 lstat > 4.55 0.000196 0 246 mmap > 4.51 0.000194 0 330 172 openat > > [...] > > ------ ----------- ----------- --------- --------- ------------------ > 100.00 0.004304 1 3748 2235 total > $ strace -c guile -c '(use-modules (guix scripts system) (guix scripts au= thenticate))' > % time seconds usecs/call calls errors syscall > ------ ----------- ----------- --------- --------- ------------------ > 54.27 0.007799 1 5735 4518 stat > 12.00 0.001724 11 149 27 futex > 9.06 0.001302 0 1328 651 openat > 7.24 0.001040 1 822 mmap > > [...] > > ------ ----------- ----------- --------- --------- ------------------ > 100.00 0.014371 1 10334 5202 total > > > (The 1st run is the current =E2=80=98guix help=E2=80=99; the 2nd run +/- = emulates what > you propose.) > > Loading all the modules translates into a lot more I/O, roughly an order > of magnitude. We=E2=80=99re talking about loading tens of modules just t= o get > at that synopsis: > > scheme@(guile-user)> ,use(guix modules) > scheme@(guile-user)> (length (source-module-closure '((guix scripts syste= m) (guix scripts authenticate)))) > $10 =3D 439 > scheme@(guile-user)> (length (source-module-closure '((guix scripts) (gui= x ui)))) > $11 =3D 31 > > Memory usage would also be very different: > > $ \time guix help >/dev/null > 0.07user 0.01system 0:00.06elapsed 128%CPU (0avgtext+0avgdata 35348maxres= ident)k > 0inputs+0outputs (0major+3906minor)pagefaults 0swaps > $ \time guile -c '(use-modules (guix scripts system) (guix scripts authen= ticate))' > 0.42user 0.05system 0:00.37elapsed 128%CPU (0avgtext+0avgdata 166916maxre= sident)k > 0inputs+0outputs (0major+15148minor)pagefaults 0swaps Thanks for the detailed measurements! It does indeed seem your approach is better, especially considering memory usage. Perhaps the commands could have been moved to dedicated modules not using much dependency at all so that their closure would have been small hence fast to load, but keeping the commands definitions local to where they are useful is definitely a nice property. > In summary, while this approach undoubtedly looks awkward to any Lisper, > I think it=E2=80=99s a good way to not contribute to the general impressi= on of > sluggishness and resource-hungriness of =E2=80=98guix=E2=80=99 commands. = :-) > >>> + (define (display-commands commands) >>> + (let* ((names (map (lambda (command) >>> + (string-join (command-name command))) >>> + commands)) >>> + (max-width (reduce max 0 (map string-length names)))) >> >> You can drop reduce and use (max (map string-length names)) instead. > > I could do (apply max (map =E2=80=A6)) but I don=E2=80=99t like the idea = of abusing > variadic argument lists in that way=E2=80=94I know, it=E2=80=99s very sub= jective. ;-) Eh, I wonder why? I may be missing something, but if max allows it, doesn't it mean it's a valid use? Anyway, just curious to know what are the grounds for this personal preference :-). > Thanks for your feedback, I=E2=80=99ll send a v2! Thanks! I'm late, but LGTM, thank you. Maxim From debbugs-submit-bounces@debbugs.gnu.org Sun Sep 13 09:03:21 2020 Received: (at 43159) by debbugs.gnu.org; 13 Sep 2020 13:03:21 +0000 Received: from localhost ([127.0.0.1]:49685 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kHRf7-0001P7-3F for submit@debbugs.gnu.org; Sun, 13 Sep 2020 09:03:21 -0400 Received: from eggs.gnu.org ([209.51.188.92]:46268) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kHRf5-0001Ot-BQ for 43159@debbugs.gnu.org; Sun, 13 Sep 2020 09:03:19 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:57839) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kHRf0-0004U0-1e; Sun, 13 Sep 2020 09:03:14 -0400 Received: from [2a01:e0a:1d:7270:af76:b9b:ca24:c465] (port=47046 helo=ribbon) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kHRez-0007fV-Jf; Sun, 13 Sep 2020 09:03:13 -0400 From: =?utf-8?Q?Ludovic_Court=C3=A8s?= To: Maxim Cournoyer Subject: Re: [bug#43159] [PATCH 1/2] scripts: Use 'define-command' and have 'guix help' use that. References: <20200901203520.21103-1-ludo@gnu.org> <20200901204136.21375-1-ludo@gnu.org> <87r1rk595p.fsf@gmail.com> <87blinx9ii.fsf@gnu.org> <878sdg6sz8.fsf@gmail.com> X-URL: http://www.fdn.fr/~lcourtes/ X-Revolutionary-Date: 28 Fructidor an 228 de la =?utf-8?Q?R=C3=A9volution?= X-PGP-Key-ID: 0x090B11993D9AEBB5 X-PGP-Key: http://www.fdn.fr/~lcourtes/ludovic.asc X-PGP-Fingerprint: 3CE4 6455 8A84 FDC6 9DB4 0CFB 090B 1199 3D9A EBB5 X-OS: x86_64-pc-linux-gnu Date: Sun, 13 Sep 2020 15:03:04 +0200 In-Reply-To: <878sdg6sz8.fsf@gmail.com> (Maxim Cournoyer's message of "Fri, 11 Sep 2020 14:58:19 -0400") Message-ID: <87lfhd7rsn.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 43159 Cc: 43159@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Hi, Maxim Cournoyer skribis: > Sorry I couldn't reply faster. No problem. I went ahead with this patch series, but nothing=E2=80=99s set= in stone and I=E2=80=99m open to further changes. > Thanks for the detailed measurements! It does indeed seem your approach > is better, especially considering memory usage. Perhaps the commands > could have been moved to dedicated modules not using much dependency at > all so that their closure would have been small hence fast to load, but > keeping the commands definitions local to where they are useful is > definitely a nice property. We can=E2=80=99t really reduce the closure of commands. In particular, (gu= ix scripts system) has to load pretty much =E2=80=9Ceverything=E2=80=9D. What we could do is use #:autoload aggressively in the (guix scripts =E2=80= =A6) modules, such that startup time would be as small as possible=E2=80=94e.g., =E2=80=98--help=E2=80=99 would not trigger loading of a zillion modules. It=E2=80=99s a bit tedious though and not necessarily helpful in the general case where one is doing something non-trivial with the command. Well dunno, we could try! >> In summary, while this approach undoubtedly looks awkward to any Lisper, >> I think it=E2=80=99s a good way to not contribute to the general impress= ion of >> sluggishness and resource-hungriness of =E2=80=98guix=E2=80=99 commands.= :-) >> >>>> + (define (display-commands commands) >>>> + (let* ((names (map (lambda (command) >>>> + (string-join (command-name command))) >>>> + commands)) >>>> + (max-width (reduce max 0 (map string-length names)))) >>> >>> You can drop reduce and use (max (map string-length names)) instead. >> >> I could do (apply max (map =E2=80=A6)) but I don=E2=80=99t like the idea= of abusing >> variadic argument lists in that way=E2=80=94I know, it=E2=80=99s very su= bjective. ;-) > > Eh, I wonder why? I may be missing something, but if max allows it, > doesn't it mean it's a valid use? Anyway, just curious to know what are > the grounds for this personal preference :-). It=E2=80=99s mostly aesthetic, but it comes from the idea that there could = be limitations on the maximum number of arguments a procedure can take, or inefficiencies with dealing with many arguments. Now, in today=E2=80=99s G= uile, there are no such issues=E2=80=A6 (And now I look really silly!) :-) Ludo=E2=80=99. From debbugs-submit-bounces@debbugs.gnu.org Sun Sep 13 19:32:47 2020 Received: (at 43159) by debbugs.gnu.org; 13 Sep 2020 23:32:47 +0000 Received: from localhost ([127.0.0.1]:52059 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kHbUF-0004yj-Fn for submit@debbugs.gnu.org; Sun, 13 Sep 2020 19:32:47 -0400 Received: from mail-qt1-f193.google.com ([209.85.160.193]:41696) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kHbUB-0004tR-Qs for 43159@debbugs.gnu.org; Sun, 13 Sep 2020 19:32:45 -0400 Received: by mail-qt1-f193.google.com with SMTP id t20so12183335qtr.8 for <43159@debbugs.gnu.org>; Sun, 13 Sep 2020 16:32:43 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-transfer-encoding; bh=wZaDZOGMYWX1Tb0X0p1o2625CCn0dC3wE7aQsLTn2Zg=; b=FGlbjHJrZmeRIKsYGYOAuI24kOr6v82YHXfjrGZ4tUFd/NtlWPgABpcLVv5ajjJsNb KR4YBFr+mZvF7h+yfTRxL9C7zBQOJ486u/KAfLsDTN5lLf6Lab2Xl78UHn2+VIBr8BEk Vlbp+sqJjBw3JJ+SK0JmfyCTITVBxX/DFZIFlB3+P3bweDNSNldBaq6zoI4Kw2hSNx8L HX+nnkewlbKjUWZfmkVJdUMQzkj6cloqy2DcQ6YQ6ciKfePYZjwj469XQVDv6TtvO1eP OzVmy45BGQtM14JUSUSrmC9+5SPDSOne9v0sfEjaiic7I7ayQgihk+VbdV6ehZmulS9d y6Jg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version:content-transfer-encoding; bh=wZaDZOGMYWX1Tb0X0p1o2625CCn0dC3wE7aQsLTn2Zg=; b=PjFuuamDxhKQNj4YN9IXJaUNX7CuBhesdkgg32EKLdorVM3a6qxtjnExoldAUWHO1D Fx5ylxI0k+eznMyqXBJh9S/W5D+g/ZC0UhyjM5ObdFeYXxy9rHsmcX/OXCK8WXhtmfl7 gb1BeOPUJFIdb5bKehoAAkomROpcKGiLq5y5+to4JWjNCvPKCZbmJajGFblhA2NHsE8I 1SVl40DZW2JJwU9KGMHF8FB4k1esUGLu+xt2Qa40m+vrEy70/H4AFxOulenoyVi0X1zs fvqoXv1R0rgwYT9a79ahkg7WWsuL7ZDBiEQC8k/HE6GPY/1KlzN7oTu/dnfSFuPnKCT2 flCQ== X-Gm-Message-State: AOAM532kir8wLpqiJ6vpRYlTT3bWC3mWDfspLr0R3CABs5RhMBvbW++a WYsfdS46zI1Vr1VNOprukkgvtyhiZ/E= X-Google-Smtp-Source: ABdhPJzI5G7KOTCYJ8R5nOrb+iFiirDc2yIgNC6oS0PImFK+wVyfRe+fZKaUImzkY6cP6TpESskOMQ== X-Received: by 2002:ac8:748c:: with SMTP id v12mr10582566qtq.200.1600039957952; Sun, 13 Sep 2020 16:32:37 -0700 (PDT) Received: from hurd (dsl-205-233-124-4.b2b2c.ca. [205.233.124.4]) by smtp.gmail.com with ESMTPSA id s15sm12756237qke.134.2020.09.13.16.32.37 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 13 Sep 2020 16:32:37 -0700 (PDT) From: Maxim Cournoyer To: Ludovic =?utf-8?Q?Court=C3=A8s?= Subject: Re: [bug#43159] [PATCH 1/2] scripts: Use 'define-command' and have 'guix help' use that. References: <20200901203520.21103-1-ludo@gnu.org> <20200901204136.21375-1-ludo@gnu.org> <87r1rk595p.fsf@gmail.com> <87blinx9ii.fsf@gnu.org> <878sdg6sz8.fsf@gmail.com> <87lfhd7rsn.fsf@gnu.org> Date: Sun, 13 Sep 2020 19:33:24 -0400 In-Reply-To: <87lfhd7rsn.fsf@gnu.org> ("Ludovic =?utf-8?Q?Court=C3=A8s=22'?= =?utf-8?Q?s?= message of "Sun, 13 Sep 2020 15:03:04 +0200") Message-ID: <87wo0x5k1n.fsf@gmail.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 43159 Cc: 43159@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Hi Ludovic! Ludovic Court=C3=A8s writes: > Hi, > > Maxim Cournoyer skribis: > >> Sorry I couldn't reply faster. > > No problem. I went ahead with this patch series, but nothing=E2=80=99s s= et in > stone and I=E2=80=99m open to further changes. No problem! I'm glad this nice UI improvement has already landed. >> Thanks for the detailed measurements! It does indeed seem your approach >> is better, especially considering memory usage. Perhaps the commands >> could have been moved to dedicated modules not using much dependency at >> all so that their closure would have been small hence fast to load, but >> keeping the commands definitions local to where they are useful is >> definitely a nice property. > > We can=E2=80=99t really reduce the closure of commands. In particular, (= guix > scripts system) has to load pretty much =E2=80=9Ceverything=E2=80=9D. > > What we could do is use #:autoload aggressively in the (guix scripts =E2= =80=A6) > modules, such that startup time would be as small as possible=E2=80=94e.g= ., > =E2=80=98--help=E2=80=99 would not trigger loading of a zillion modules. > > It=E2=80=99s a bit tedious though and not necessarily helpful in the gene= ral > case where one is doing something non-trivial with the command. Well > dunno, we could try! Seems like too much micro-management. This further solidifies your design choice as the right one :-). >>> In summary, while this approach undoubtedly looks awkward to any Lisper, >>> I think it=E2=80=99s a good way to not contribute to the general impres= sion of >>> sluggishness and resource-hungriness of =E2=80=98guix=E2=80=99 commands= . :-) >>> >>>>> + (define (display-commands commands) >>>>> + (let* ((names (map (lambda (command) >>>>> + (string-join (command-name command))) >>>>> + commands)) >>>>> + (max-width (reduce max 0 (map string-length names)))) >>>> >>>> You can drop reduce and use (max (map string-length names)) instead. >>> >>> I could do (apply max (map =E2=80=A6)) but I don=E2=80=99t like the ide= a of abusing >>> variadic argument lists in that way=E2=80=94I know, it=E2=80=99s very s= ubjective. ;-) >> >> Eh, I wonder why? I may be missing something, but if max allows it, >> doesn't it mean it's a valid use? Anyway, just curious to know what are >> the grounds for this personal preference :-). > > It=E2=80=99s mostly aesthetic, but it comes from the idea that there coul= d be > limitations on the maximum number of arguments a procedure can take, or > inefficiencies with dealing with many arguments. Now, in today=E2=80=99s= Guile, > there are no such issues=E2=80=A6 (And now I look really silly!) :-) Ha! Thanks for explaining. Now I know I can shamelessly continue using apply on procedures accepting N arguments :-). Maxim From unknown Sat Sep 20 11:29:44 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Mon, 12 Oct 2020 11:24:08 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator