all messages for Guix-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* [bug#28452] [PATCH 0/6] On-line doc and search for services
@ 2017-09-13 21:17 Ludovic Courtès
  2017-09-13 21:24 ` [bug#28452] [PATCH 1/6] ui: Generalize relevance computation Ludovic Courtès
  2017-09-14  7:37 ` [bug#28452] [PATCH 0/6] On-line doc and search for services Christopher Baines
  0 siblings, 2 replies; 9+ messages in thread
From: Ludovic Courtès @ 2017-09-13 21:17 UTC (permalink / raw)
  To: 28452

Hello!

This patch series adds a new ‘guix system search’ command to search
through the available services types:

--8<---------------cut here---------------start------------->8---
$ ./pre-inst-env guix system search anony network
name: tor
location: gnu/services/networking.scm:670:2
extends: shepherd-root account activate
description: Run the Tor (https://torproject.org) anonymous networking daemon.
relevance: 9

name: static-networking
location: gnu/services/networking.scm:248:2
extends: shepherd-root etc
description: Turn up the specified network interfaces upon startup, with the given IP
+ address, gateway, netmask, and so on.  The value for services of this type is a list of
+ `static-networking' objects, one per network interface.
relevance: 6

name: network-manager
location: gnu/services/networking.scm:947:4
extends: shepherd-root dbus polkit activate profile
description: Run NetworkManager (https://wiki.gnome.org/Projects/NetworkManager), a
+ network management daemon that aims to simplify wired and wireless networking.
relevance: 6

[...]
--8<---------------cut here---------------end--------------->8---

I think this can be pretty useful.  It also works with service types
that have #f as their ‘description’ field, which is the vast majority of
them (help welcome!).

Possible improvements and related things:

  • Display each field and value of the default value of services.

  • Add ‘guix system edit’ or ‘guix edit --service’?

  • Add a web UI to browse services.

Comments welcome!

Ludo’.

Ludovic Courtès (6):
  ui: Generalize relevance computation.
  services: Add a description and location for each service type.
  services: Add 'fold-service-types'.
  guix system: Add 'search' command.
  services: base: Add descriptions.
  services: networking: Add descriptions.

 Makefile.am                    |   1 +
 doc/guix.texi                  |  42 ++++++++++++
 gnu/services.scm               |  37 ++++++++++-
 gnu/services/base.scm          |  85 ++++++++++++++++++++----
 gnu/services/networking.scm    |  55 +++++++++++++---
 guix/scripts/package.scm       |  21 +-----
 guix/scripts/system.scm        |  13 +++-
 guix/scripts/system/search.scm | 144 +++++++++++++++++++++++++++++++++++++++++
 guix/ui.scm                    |  44 +++++++++++++
 po/guix/POTFILES.in            |   1 +
 po/packages/POTFILES.in        |   2 +
 tests/guix-system.sh           |   6 +-
 12 files changed, 403 insertions(+), 48 deletions(-)
 create mode 100644 guix/scripts/system/search.scm

-- 
2.14.1

^ permalink raw reply	[flat|nested] 9+ messages in thread

* [bug#28452] [PATCH 1/6] ui: Generalize relevance computation.
  2017-09-13 21:17 [bug#28452] [PATCH 0/6] On-line doc and search for services Ludovic Courtès
@ 2017-09-13 21:24 ` Ludovic Courtès
  2017-09-13 21:24   ` [bug#28452] [PATCH 2/6] services: Add a description and location for each service type Ludovic Courtès
                     ` (4 more replies)
  2017-09-14  7:37 ` [bug#28452] [PATCH 0/6] On-line doc and search for services Christopher Baines
  1 sibling, 5 replies; 9+ messages in thread
From: Ludovic Courtès @ 2017-09-13 21:24 UTC (permalink / raw)
  To: 28452

* guix/ui.scm (relevance, package-relevance): New procedures.
(%package-metrics): New variable.
* guix/scripts/package.scm (find-packages-by-description)[score]
[package-score]: Remove.  Use 'package-relevance' instead.
---
 guix/scripts/package.scm | 21 +--------------------
 guix/ui.scm              | 43 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+), 20 deletions(-)

diff --git a/guix/scripts/package.scm b/guix/scripts/package.scm
index 9ec6950c4..4adc70522 100644
--- a/guix/scripts/package.scm
+++ b/guix/scripts/package.scm
@@ -246,27 +246,8 @@ specified in MANIFEST, a manifest object."
   "Return two values: the list of packages whose name, synopsis, or
 description matches at least one of REGEXPS sorted by relevance, and the list
 of relevance scores."
-  (define (score str)
-    (let ((counts (filter-map (lambda (regexp)
-                                (match (regexp-exec regexp str)
-                                  (#f #f)
-                                  (m  (match:count m))))
-                              regexps)))
-      ;; Compute a score that's proportional to the number of regexps matched
-      ;; and to the number of matches for each regexp.
-      (* (length counts) (reduce + 0 counts))))
-
-  (define (package-score package)
-    (+ (* 3 (score (package-name package)))
-       (* 2 (match (package-synopsis package)
-              ((? string? str) (score (P_ str)))
-              (#f              0)))
-       (match (package-description package)
-         ((? string? str) (score (P_ str)))
-         (#f              0))))
-
   (let ((matches (fold-packages (lambda (package result)
-                                  (match (package-score package)
+                                  (match (package-relevance package regexps)
                                     ((? zero?)
                                      result)
                                     (score
diff --git a/guix/ui.scm b/guix/ui.scm
index b0108d070..a51877c04 100644
--- a/guix/ui.scm
+++ b/guix/ui.scm
@@ -85,6 +85,8 @@
             string->recutils
             package->recutils
             package-specification->name+version+output
+            relevance
+            package-relevance
             string->generations
             string->duration
             matching-generations
@@ -1024,6 +1026,47 @@ WIDTH columns.  EXTRA-FIELDS is a list of symbol/value pairs to emit."
             extra-fields)
   (newline port))
 
+(define (relevance obj regexps metrics)
+  "Compute a \"relevance score\" for OBJ as a function of its number of
+matches of REGEXPS and accordingly to METRICS.  METRICS is list of
+field/weight pairs, where FIELD is a procedure that returns a string
+describing OBJ, and WEIGHT is a positive integer denoting the weight of this
+field in the final score.
+
+A score of zero means that OBJ does not match any of REGEXPS.  The higher the
+score, the more relevant OBJ is to REGEXPS."
+  (define (score str)
+    (let ((counts (filter-map (lambda (regexp)
+                                (match (regexp-exec regexp str)
+                                  (#f #f)
+                                  (m  (match:count m))))
+                              regexps)))
+      ;; Compute a score that's proportional to the number of regexps matched
+      ;; and to the number of matches for each regexp.
+      (* (length counts) (reduce + 0 counts))))
+
+  (fold (lambda (metric relevance)
+          (match metric
+            ((field . weight)
+             (match (field obj)
+               (#f  relevance)
+               (str (+ relevance
+                       (* (score str) weight)))))))
+        0
+        metrics))
+
+(define %package-metrics
+  ;; Metrics used to compute the "relevance score" of a package against a set
+  ;; of regexps.
+  `((,package-name . 3)
+    (,package-synopsis-string . 2)
+    (,package-description-string . 1)))
+
+(define (package-relevance package regexps)
+  "Return a score denoting the relevance of PACKAGE for REGEXPS.  A score of
+zero means that PACKAGE does not match any of REGEXPS."
+  (relevance package regexps %package-metrics))
+
 (define (string->generations str)
   "Return the list of generations matching a pattern in STR.  This function
 accepts the following patterns: \"1\", \"1,2,3\", \"1..9\", \"1..\", \"..9\"."
-- 
2.14.1

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [bug#28452] [PATCH 2/6] services: Add a description and location for each service type.
  2017-09-13 21:24 ` [bug#28452] [PATCH 1/6] ui: Generalize relevance computation Ludovic Courtès
@ 2017-09-13 21:24   ` Ludovic Courtès
  2017-09-13 21:24   ` [bug#28452] [PATCH 3/6] services: Add 'fold-service-types' Ludovic Courtès
                     ` (3 subsequent siblings)
  4 siblings, 0 replies; 9+ messages in thread
From: Ludovic Courtès @ 2017-09-13 21:24 UTC (permalink / raw)
  To: 28452

* gnu/services.scm (<service-type>)[description, location]: New field.
* doc/guix.texi (Service Types and Services): Document 'description'.
---
 doc/guix.texi    |  4 ++++
 gnu/services.scm | 13 ++++++++++++-
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 063369122..513493b86 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -18020,6 +18020,10 @@ Udev extensions are composed into a list of rules, but the udev service
 value is itself a @code{<udev-configuration>} record.  So here, we
 extend that record by appending the list of rules it contains to the
 list of contributed rules.
+
+@item description
+This is a string giving an overview of the service type.  The string can
+contain Texinfo markup (@pxref{Overview,,, texinfo, GNU Texinfo}).
 @end table
 
 There can be only one instance of an extensible service type such as
diff --git a/gnu/services.scm b/gnu/services.scm
index 8ef1ae7c7..83a163b76 100644
--- a/gnu/services.scm
+++ b/gnu/services.scm
@@ -49,6 +49,9 @@
             service-type-compose
             service-type-extend
             service-type-default-value
+            service-type-description
+            service-type-location
+
 
             service
             service?
@@ -145,7 +148,15 @@
 
   ;; Optional default value for instances of this type.
   (default-value service-type-default-value       ;Any
-                 (default &no-default-value)))
+                 (default &no-default-value))
+
+  ;; Meta-data.
+  (description  service-type-description          ;string
+                (default #f))
+  (location     service-type-location             ;<location>
+                (default (and=> (current-source-location)
+                                source-properties->location))
+                (innate)))
 
 (define (write-service-type type port)
   (format port "#<service-type ~a ~a>"
-- 
2.14.1

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [bug#28452] [PATCH 3/6] services: Add 'fold-service-types'.
  2017-09-13 21:24 ` [bug#28452] [PATCH 1/6] ui: Generalize relevance computation Ludovic Courtès
  2017-09-13 21:24   ` [bug#28452] [PATCH 2/6] services: Add a description and location for each service type Ludovic Courtès
@ 2017-09-13 21:24   ` Ludovic Courtès
  2017-09-13 21:24   ` [bug#28452] [PATCH 4/6] guix system: Add 'search' command Ludovic Courtès
                     ` (2 subsequent siblings)
  4 siblings, 0 replies; 9+ messages in thread
From: Ludovic Courtès @ 2017-09-13 21:24 UTC (permalink / raw)
  To: 28452

* gnu/services.scm (%distro-root-directory, %service-type-path): New
variables.
(fold-service-types): New procedure.
---
 gnu/services.scm | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/gnu/services.scm b/gnu/services.scm
index 83a163b76..2ebd701a5 100644
--- a/gnu/services.scm
+++ b/gnu/services.scm
@@ -23,6 +23,7 @@
   #:use-module (guix store)
   #:use-module (guix records)
   #:use-module (guix profiles)
+  #:use-module (guix discovery)
   #:use-module (guix sets)
   #:use-module (guix ui)
   #:use-module ((guix utils) #:select (source-properties->location))
@@ -52,6 +53,8 @@
             service-type-description
             service-type-location
 
+            %service-type-path
+            fold-service-types
 
             service
             service?
@@ -165,6 +168,27 @@
 
 (set-record-type-printer! <service-type> write-service-type)
 
+(define %distro-root-directory
+  ;; Absolute file name of the module hierarchy.
+  (dirname (search-path %load-path "guix.scm")))
+
+(define %service-type-path
+  ;; Search path for service types.
+  (make-parameter `((,%distro-root-directory . "gnu/services")
+                    (,%distro-root-directory . "gnu/system"))))
+
+(define* (fold-service-types proc seed
+                             #:optional
+                             (modules (all-modules (%service-type-path))))
+  "For each service type exported by one of MODULES, call (PROC RESULT).  SEED
+is used as the initial value of RESULT."
+  (fold-module-public-variables (lambda (object result)
+                                  (if (service-type? object)
+                                      (proc object result)
+                                      result))
+                                '()
+                                modules))
+
 ;; Services of a given type.
 (define-record-type <service>
   (make-service type value)
-- 
2.14.1

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [bug#28452] [PATCH 4/6] guix system: Add 'search' command.
  2017-09-13 21:24 ` [bug#28452] [PATCH 1/6] ui: Generalize relevance computation Ludovic Courtès
  2017-09-13 21:24   ` [bug#28452] [PATCH 2/6] services: Add a description and location for each service type Ludovic Courtès
  2017-09-13 21:24   ` [bug#28452] [PATCH 3/6] services: Add 'fold-service-types' Ludovic Courtès
@ 2017-09-13 21:24   ` Ludovic Courtès
  2017-09-13 21:24   ` [bug#28452] [PATCH 5/6] services: base: Add descriptions Ludovic Courtès
  2017-09-13 21:24   ` [bug#28452] [PATCH 6/6] services: networking: " Ludovic Courtès
  4 siblings, 0 replies; 9+ messages in thread
From: Ludovic Courtès @ 2017-09-13 21:24 UTC (permalink / raw)
  To: 28452

* guix/scripts/system.scm (resolve-subcommand): New procedure.
(process-command): Handle 'search'.
(guix-system): Likewise.
(show-help): Augment.
* guix/scripts/system/search.scm: New file.
* po/guix/POTFILES.in: Add it.
* Makefile.am (MODULES): Add it.
* guix/ui.scm (%text-width): Export.
* doc/guix.texi (Invoking guix system): Document it.
(Service Types and Services): Mention 'guix system search'.
* tests/guix-system.sh: Test it.
---
 Makefile.am                    |   1 +
 doc/guix.texi                  |  40 +++++++++++-
 guix/scripts/system.scm        |  13 +++-
 guix/scripts/system/search.scm | 144 +++++++++++++++++++++++++++++++++++++++++
 guix/ui.scm                    |   1 +
 po/guix/POTFILES.in            |   1 +
 tests/guix-system.sh           |   6 +-
 7 files changed, 202 insertions(+), 4 deletions(-)
 create mode 100644 guix/scripts/system/search.scm

diff --git a/Makefile.am b/Makefile.am
index 4c2e77d19..f621ba8c1 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -164,6 +164,7 @@ MODULES =					\
   guix/scripts/authenticate.scm			\
   guix/scripts/refresh.scm			\
   guix/scripts/system.scm			\
+  guix/scripts/system/search.scm		\
   guix/scripts/lint.scm				\
   guix/scripts/challenge.scm			\
   guix/scripts/import/cran.scm			\
diff --git a/doc/guix.texi b/doc/guix.texi
index 513493b86..3ca5eebcf 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -17391,6 +17391,42 @@ operating system is instantiated.  Currently the following values are
 supported:
 
 @table @code
+@item search
+Display available service type definitions that match the given regular
+expressions, sorted by relevance:
+
+@example
+$ guix system search console font
+name: console-fonts
+location: gnu/services/base.scm:729:2
+extends: shepherd-root
+description: Install the given fonts on the specified ttys (fonts are
++ per virtual console on GNU/Linux).  The value of this service is a list
++ of tty/font pairs like:
++ 
++      '(("tty1" . "LatGrkCyr-8x16"))
+relevance: 20
+
+name: mingetty
+location: gnu/services/base.scm:1048:2
+extends: shepherd-root
+description: Provide console login using the `mingetty' program.
+relevance: 2
+
+name: login
+location: gnu/services/base.scm:775:2
+extends: pam
+description: Provide a console log-in service as specified by its
++ configuration value, a `login-configuration' object.
+relevance: 2
+
+@dots{}
+@end example
+
+As for @command{guix package --search}, the result is written in
+@code{recutils} format, which makes it easy to filter the output
+(@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).
+
 @item reconfigure
 Build the operating system described in @var{file}, activate it, and
 switch to it@footnote{This action (and the related actions
@@ -18023,7 +18059,9 @@ list of contributed rules.
 
 @item description
 This is a string giving an overview of the service type.  The string can
-contain Texinfo markup (@pxref{Overview,,, texinfo, GNU Texinfo}).
+contain Texinfo markup (@pxref{Overview,,, texinfo, GNU Texinfo}).  The
+@command{guix system search} command searches these strings and displays
+them (@pxref{Invoking guix system}).
 @end table
 
 There can be only one instance of an extensible service type such as
diff --git a/guix/scripts/system.scm b/guix/scripts/system.scm
index ea35fcdbc..567d8bb64 100644
--- a/guix/scripts/system.scm
+++ b/guix/scripts/system.scm
@@ -73,7 +73,6 @@
   "Read the operating-system declaration from FILE and return it."
   (load* file %user-module))
 
-
 \f
 ;;;
 ;;; Installation.
@@ -751,6 +750,8 @@ Some ACTIONS support additional ARGS.\n"))
   (newline)
   (display (G_ "The valid values for ACTION are:\n"))
   (newline)
+  (display (G_ "\
+   search           search for existing service types\n"))
   (display (G_ "\
    reconfigure      switch to a new operating system configuration\n"))
   (display (G_ "\
@@ -937,6 +938,12 @@ resulting from command-line parsing."
                              #:gc-root (assoc-ref opts 'gc-root)))))
         #:system system))))
 
+(define (resolve-subcommand name)
+  (let ((module (resolve-interface
+                 `(guix scripts system ,(string->symbol name))))
+        (proc (string->symbol (string-append "guix-system-" name))))
+    (module-ref module proc)))
+
 (define (process-command command args opts)
   "Process COMMAND, one of the 'guix system' sub-commands.  ARGS is its
 argument list and OPTS is the option alist."
@@ -949,6 +956,8 @@ argument list and OPTS is the option alist."
                       ((pattern) pattern)
                       (x (leave (G_ "wrong number of arguments~%"))))))
        (list-generations pattern)))
+    ((search)
+     (apply (resolve-subcommand "search") args))
     ;; The following commands need to use the store, but they do not need an
     ;; operating system configuration file.
     ((switch-generation)
@@ -978,7 +987,7 @@ argument list and OPTS is the option alist."
           (case action
             ((build container vm vm-image disk-image reconfigure init
               extension-graph shepherd-graph list-generations roll-back
-              switch-generation)
+              switch-generation search)
              (alist-cons 'action action result))
             (else (leave (G_ "~a: unknown action~%") action))))))
 
diff --git a/guix/scripts/system/search.scm b/guix/scripts/system/search.scm
new file mode 100644
index 000000000..b4f790c9b
--- /dev/null
+++ b/guix/scripts/system/search.scm
@@ -0,0 +1,144 @@
+;;; GNU Guix --- Functional package management for GNU
+;;; Copyright © 2017 Ludovic Courtès <ludo@gnu.org>
+;;;
+;;; This file is part of GNU Guix.
+;;;
+;;; GNU Guix is free software; you can redistribute it and/or modify it
+;;; under the terms of the GNU General Public License as published by
+;;; the Free Software Foundation; either version 3 of the License, or (at
+;;; your option) any later version.
+;;;
+;;; GNU Guix is distributed in the hope that it will be useful, but
+;;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;;; GNU General Public License for more details.
+;;;
+;;; You should have received a copy of the GNU General Public License
+;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
+
+(define-module (guix scripts system search)
+  #:use-module (guix ui)
+  #:use-module (guix utils)
+  #:use-module (gnu services)
+  #:use-module (srfi srfi-1)
+  #:use-module (srfi srfi-11)
+  #:use-module (srfi srfi-26)
+  #:use-module (ice-9 regex)
+  #:use-module (ice-9 match)
+  #:export (service-type->recutils
+            find-service-types
+            guix-system-search))
+
+;;; Commentary:
+;;;
+;;; Implement the 'guix system search' command, which searches among the
+;;; available service types.
+;;;
+;;; Code:
+
+(define service-type-name*
+  (compose symbol->string service-type-name))
+
+(define* (service-type->recutils type port
+                                 #:optional (width (%text-width))
+                                 #:key (extra-fields '()))
+  "Write to PORT a recutils record of TYPE, arranging to fit within WIDTH
+columns."
+  (define width*
+    ;; The available number of columns once we've taken into account space for
+    ;; the initial "+ " prefix.
+    (if (> width 2) (- width 2) width))
+
+  (define (extensions->recutils extensions)
+    (let ((list (string-join (map (compose service-type-name*
+                                           service-extension-target)
+                                  extensions))))
+      (string->recutils
+       (fill-paragraph list width*
+                       (string-length "extends: ")))))
+
+  ;; Note: Don't i18n field names so that people can post-process it.
+  (format port "name: ~a~%" (service-type-name type))
+  (format port "location: ~a~%"
+          (or (and=> (service-type-location type) location->string)
+              (G_ "unknown")))
+
+  (format port "extends: ~a~%"
+          (extensions->recutils (service-type-extensions type)))
+
+  (when (service-type-description type)
+    (format port "~a~%"
+            (string->recutils
+             (string-trim-right
+              (parameterize ((%text-width width*))
+                (texi->plain-text
+                 (string-append "description: "
+                                (or (and=> (service-type-description type) P_)
+                                    ""))))
+              #\newline))))
+
+  (for-each (match-lambda
+              ((field . value)
+               (let ((field (symbol->string field)))
+                 (format port "~a: ~a~%"
+                         field
+                         (fill-paragraph (object->string value) width*
+                                         (string-length field))))))
+            extra-fields)
+  (newline port))
+
+(define (service-type-description-string type)
+  "Return the rendered and localised description of TYPE, a service type."
+  (and=> (service-type-description type)
+         (compose texi->plain-text P_)))
+
+(define %service-type-metrics
+  ;; Metrics used to estimate the relevance of a search result.
+  `((,service-type-name* . 3)
+    (,service-type-description-string . 2)
+    (,(lambda (type)
+        (match (and=> (service-type-location type) location-file)
+          ((? string? file)
+           (basename file ".scm"))
+          (#f
+           "")))
+     . 1)))
+
+(define (find-service-types regexps)
+  "Return two values: the list of service types whose name or description
+matches at least one of REGEXPS sorted by relevance, and the list of relevance
+scores."
+  (let ((matches (fold-service-types
+                  (lambda (type result)
+                    (match (relevance type regexps
+                                      %service-type-metrics)
+                      ((? zero?)
+                       result)
+                      (score
+                       (cons (list type score) result))))
+                  '())))
+    (unzip2 (sort matches
+                  (lambda (m1 m2)
+                    (match m1
+                      ((type1 score1)
+                       (match m2
+                         ((type2 score2)
+                          (if (= score1 score2)
+                              (string>? (service-type-name* type1)
+                                        (service-type-name* type2))
+                              (> score1 score2)))))))))))
+
+\f
+(define (guix-system-search . args)
+  (with-error-handling
+    (let ((regexps (map (cut make-regexp* <> regexp/icase) args)))
+      (leave-on-EPIPE
+       (let-values (((services scores)
+                     (find-service-types regexps)))
+         (for-each (lambda (service score)
+                     (service-type->recutils service
+                                             (current-output-port)
+                                             #:extra-fields
+                                             `((relevance . ,score))))
+                   services
+                   scores))))))
diff --git a/guix/ui.scm b/guix/ui.scm
index a51877c04..6dfc8c7a5 100644
--- a/guix/ui.scm
+++ b/guix/ui.scm
@@ -79,6 +79,7 @@
             read/eval-package-expression
             location->string
             fill-paragraph
+            %text-width
             texi->plain-text
             package-description-string
             package-synopsis-string
diff --git a/po/guix/POTFILES.in b/po/guix/POTFILES.in
index b8e0aca87..e3f767cc6 100644
--- a/po/guix/POTFILES.in
+++ b/po/guix/POTFILES.in
@@ -19,6 +19,7 @@ guix/scripts/pull.scm
 guix/scripts/substitute.scm
 guix/scripts/authenticate.scm
 guix/scripts/system.scm
+guix/scripts/system/search.scm
 guix/scripts/lint.scm
 guix/scripts/publish.scm
 guix/scripts/edit.scm
diff --git a/tests/guix-system.sh b/tests/guix-system.sh
index de6db0928..d575795ea 100644
--- a/tests/guix-system.sh
+++ b/tests/guix-system.sh
@@ -1,5 +1,5 @@
 # GNU Guix --- Functional package management for GNU
-# Copyright © 2014, 2015, 2016 Ludovic Courtès <ludo@gnu.org>
+# Copyright © 2014, 2015, 2016, 2017 Ludovic Courtès <ludo@gnu.org>
 #
 # This file is part of GNU Guix.
 #
@@ -215,3 +215,7 @@ EOF
 # In both cases 'my-torrc' should be properly resolved.
 guix system build "$tmpdir/config.scm" -n
 (cd "$tmpdir"; guix system build "config.scm" -n)
+
+# Searching.
+guix system search tor | grep "^name: tor"
+guix system search anonym network | grep "^name: tor"
-- 
2.14.1

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [bug#28452] [PATCH 5/6] services: base: Add descriptions.
  2017-09-13 21:24 ` [bug#28452] [PATCH 1/6] ui: Generalize relevance computation Ludovic Courtès
                     ` (2 preceding siblings ...)
  2017-09-13 21:24   ` [bug#28452] [PATCH 4/6] guix system: Add 'search' command Ludovic Courtès
@ 2017-09-13 21:24   ` Ludovic Courtès
  2017-09-13 21:24   ` [bug#28452] [PATCH 6/6] services: networking: " Ludovic Courtès
  4 siblings, 0 replies; 9+ messages in thread
From: Ludovic Courtès @ 2017-09-13 21:24 UTC (permalink / raw)
  To: 28452

* gnu/services/base.scm (fstab-service-type)
(file-system-service-type, urandom-seed-service-type)
(session-environment-service-type)
(console-font-service-type)
(login-service-type, agetty-service-type)
(mingetty-service-type, nscd-service-type)
(pam-limits-service-type, guix-service-type)
(guix-publish-service-type, udev-service-type)
(gpm-service-type): Add 'description' field.
* po/packages/POTFILES.in: Add gnu/services/base.scm.
---
 gnu/services/base.scm   | 85 +++++++++++++++++++++++++++++++++++++++++--------
 po/packages/POTFILES.in |  1 +
 2 files changed, 72 insertions(+), 14 deletions(-)

diff --git a/gnu/services/base.scm b/gnu/services/base.scm
index b8feb725d..10c8f1b6a 100644
--- a/gnu/services/base.scm
+++ b/gnu/services/base.scm
@@ -210,7 +210,10 @@
                  (list (service-extension etc-service-type
                                           file-systems->fstab)))
                 (compose concatenate)
-                (extend append)))
+                (extend append)
+                (description
+                 "Populate the @file{/etc/fstab} based on the given file
+system objects.")))
 
 (define %root-file-system-shepherd-service
   (shepherd-service
@@ -349,7 +352,10 @@ FILE-SYSTEM."
                        (service-extension fstab-service-type
                                           identity)))
                 (compose concatenate)
-                (extend append)))
+                (extend append)
+                (description
+                 "Provide Shepherd services to mount and unmount the given
+file systems, as well as corresponding @file{/etc/fstab} entries.")))
 
 (define user-unmount-service-type
   (shepherd-service-type
@@ -545,7 +551,11 @@ stopped before 'kill' is called."
   (service-type (name 'urandom-seed)
                 (extensions
                  (list (service-extension shepherd-root-service-type
-                                          urandom-seed-shepherd-service)))))
+                                          urandom-seed-shepherd-service)))
+                (description
+                 "Seed the @file{/dev/urandom} pseudo-random number
+generator (RNG) with the value recorded when the system was last shut
+down.")))
 
 (define (urandom-seed-service)
   (service urandom-seed-service-type #f))
@@ -613,7 +623,15 @@ to add @var{device} to the kernel's entropy pool.  The service will fail if
              (list `("environment"
                      ,(environment-variables->environment-file vars)))))))
    (compose concatenate)
-   (extend append)))
+   (extend append)
+   (description
+    "Populate @file{/etc/environment} with the specified environment
+variables.  The value of this service is a list of name/value pairs for
+environments variables, such as:
+
+@example
+'((\"TZ\" . \"Canada/Pacific\"))
+@end example\n")))
 
 (define (session-environment-service vars)
   "Return a service that builds the @file{/etc/environment}, which can be read
@@ -713,7 +731,15 @@ strings or string-valued gexps."
                  (list (service-extension shepherd-root-service-type
                                           console-font-shepherd-services)))
                 (compose concatenate)
-                (extend append)))
+                (extend append)
+                (description
+                 "Install the given fonts on the specified ttys (fonts are per
+virtual console on GNU/Linux).  The value of this service is a list of
+tty/font pairs like:
+
+@example
+'((\"tty1\" . \"LatGrkCyr-8x16\"))
+@end example\n")))
 
 (define* (console-font-service tty #:optional (font "LatGrkCyr-8x16"))
   "This procedure is deprecated in favor of @code{console-font-service-type}.
@@ -748,7 +774,10 @@ Return a service that sets up Unicode support in @var{tty} and loads
 (define login-service-type
   (service-type (name 'login)
                 (extensions (list (service-extension pam-root-service-type
-                                                     login-pam-service)))))
+                                                     login-pam-service)))
+                (description
+                 "Provide a console log-in service as specified by its
+configuration value, a @code{login-configuration} object.")))
 
 (define* (login-service #:optional (config (login-configuration)))
   "Return a service configure login according to @var{config}, which specifies
@@ -964,7 +993,10 @@ the message of the day, among other things."
 (define agetty-service-type
   (service-type (name 'agetty)
                 (extensions (list (service-extension shepherd-root-service-type
-                                                     agetty-shepherd-service)))))
+                                                     agetty-shepherd-service)))
+                (description
+                 "Provide console login using the @command{agetty}
+program.")))
 
 (define* (agetty-service config)
   "Return a service to run agetty according to @var{config}, which specifies
@@ -1015,7 +1047,10 @@ the tty to run, among other things."
 (define mingetty-service-type
   (service-type (name 'mingetty)
                 (extensions (list (service-extension shepherd-root-service-type
-                                                     mingetty-shepherd-service)))))
+                                                     mingetty-shepherd-service)))
+                (description
+                 "Provide console login using the @command{mingetty}
+program.")))
 
 (define* (mingetty-service config)
   "Return a service to run mingetty according to @var{config}, which specifies
@@ -1184,7 +1219,11 @@ the tty to run, among other things."
                            (inherit config)
                            (name-services (append
                                            (nscd-configuration-name-services config)
-                                           name-services)))))))
+                                           name-services)))))
+                (description
+                 "Runs libc's @dfn{name service cache daemon} (nscd) with the
+given configuration---an @code{<nscd-configuration>} object.  @xref{Name
+Service Switch}, for an example.")))
 
 (define* (nscd-service #:optional (config %nscd-default-configuration))
   "Return a service that runs libc's name service cache daemon (nscd) with the
@@ -1280,7 +1319,11 @@ information on the configuration file syntax."
      (extensions
       (list (service-extension etc-service-type security-limits)
             (service-extension pam-root-service-type
-                               (lambda _ (list pam-extension))))))))
+                               (lambda _ (list pam-extension)))))
+     (description
+      "Install the specified resource usage limits by populating
+@file{/etc/security/limits.conf} and using the @code{pam_limits}
+authentication module."))))
 
 (define* (pam-limits-service #:optional (limits '()))
   "Return a service that makes selected programs respect the list of
@@ -1456,7 +1499,9 @@ failed to register hydra.gnu.org public key: ~a~%" status))))))))
           (service-extension activation-service-type guix-activation)
           (service-extension profile-service-type
                              (compose list guix-configuration-guix))))
-   (default-value (guix-configuration))))
+   (default-value (guix-configuration))
+   (description
+    "Run the build daemon of GNU@tie{}Guix, aka. @command{guix-daemon}.")))
 
 (define* (guix-service #:optional (config %default-guix-configuration))
   "Return a service that runs the Guix build daemon according to
@@ -1554,7 +1599,10 @@ failed to register hydra.gnu.org public key: ~a~%" status))))))))
                                           (const %guix-publish-accounts))
                        (service-extension activation-service-type
                                           guix-publish-activation)))
-                (default-value (guix-publish-configuration))))
+                (default-value (guix-publish-configuration))
+                (description
+                 "Add a Shepherd service running @command{guix publish}, a
+command that allows you to share pre-built binaries with others over HTTP.")))
 
 (define* (guix-publish-service #:key (guix guix) (port 80) (host "localhost"))
   "Return a service that runs @command{guix publish} listening on @var{host}
@@ -1726,7 +1774,11 @@ item of @var{packages}."
                             (($ <udev-configuration> udev initial-rules)
                              (udev-configuration
                               (udev udev)
-                              (rules (append initial-rules rules)))))))))
+                              (rules (append initial-rules rules)))))))
+                (description
+                 "Run @command{udev}, which populates the @file{/dev}
+directory dynamically.  Get extra rules from the packages listed in the
+@code{rules} field of its value, @code{udev-configuration} object.")))
 
 (define* (udev-service #:key (udev eudev) (rules '()))
   "Run @var{udev}, which populates the @file{/dev} directory dynamically.  Get
@@ -1797,7 +1849,12 @@ extra rules from the packages listed in @var{rules}."
   (service-type (name 'gpm)
                 (extensions
                  (list (service-extension shepherd-root-service-type
-                                          gpm-shepherd-service)))))
+                                          gpm-shepherd-service)))
+                (description
+                 "Run GPM, the general-purpose mouse daemon, with the given
+command-line options.  GPM allows users to use the mouse in the console,
+notably to select, copy, and paste text.  The default options use the
+@code{ps2} protocol, which works for both USB and PS/2 mice.")))
 
 (define* (gpm-service #:key (gpm gpm)
                       (options '("-m" "/dev/input/mice" "-t" "ps2")))
diff --git a/po/packages/POTFILES.in b/po/packages/POTFILES.in
index 32d34d645..d111a6ffc 100644
--- a/po/packages/POTFILES.in
+++ b/po/packages/POTFILES.in
@@ -57,3 +57,4 @@ gnu/packages/webkit.scm
 gnu/packages/web.scm
 gnu/packages/wordnet.scm
 gnu/packages/xiph.scm
+gnu/services/base.scm
-- 
2.14.1

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [bug#28452] [PATCH 6/6] services: networking: Add descriptions.
  2017-09-13 21:24 ` [bug#28452] [PATCH 1/6] ui: Generalize relevance computation Ludovic Courtès
                     ` (3 preceding siblings ...)
  2017-09-13 21:24   ` [bug#28452] [PATCH 5/6] services: base: Add descriptions Ludovic Courtès
@ 2017-09-13 21:24   ` Ludovic Courtès
  4 siblings, 0 replies; 9+ messages in thread
From: Ludovic Courtès @ 2017-09-13 21:24 UTC (permalink / raw)
  To: 28452

* gnu/services/networking.scm (static-networking-service-type)
(ntp-service-type, inetd-service-type, tor-service-type)
(tor-hidden-service-type, bitlbee-service-type)
(wicd-service-type, network-manager-service-type)
(connman-service-type, openvswitch-service-type): Add 'description'
field.
* po/packages/POTFILES.in: Add gnu/services/networking.scm.
---
 gnu/services/networking.scm | 55 ++++++++++++++++++++++++++++++++++++---------
 po/packages/POTFILES.in     |  1 +
 2 files changed, 46 insertions(+), 10 deletions(-)

diff --git a/gnu/services/networking.scm b/gnu/services/networking.scm
index b45008de6..fbedaa5b3 100644
--- a/gnu/services/networking.scm
+++ b/gnu/services/networking.scm
@@ -253,7 +253,12 @@ fe80::1%lo0 apps.facebook.com\n")
                   (service-extension etc-service-type
                                      static-networking-etc-files)))
                 (compose concatenate)
-                (extend append)))
+                (extend append)
+                (description
+                 "Turn up the specified network interfaces upon startup,
+with the given IP address, gateway, netmask, and so on.  The value for
+services of this type is a list of @code{static-networking} objects, one per
+network interface.")))
 
 (define* (static-networking-service interface ip
                                     #:key
@@ -422,7 +427,11 @@ restrict -6 ::1\n"))
                        (service-extension account-service-type
                                           (const %ntp-accounts))
                        (service-extension activation-service-type
-                                          ntp-service-activation)))))
+                                          ntp-service-activation)))
+                (description
+                 "Run the @command{ntpd}, the Network Time Protocol (NTP)
+daemon of the @uref{http://www.ntp.org, Network Time Foundation}.  The daemon
+will keep the system clock synchronized with that of the given servers.")))
 
 (define* (ntp-service #:key (ntp ntp)
                       (servers %ntp-servers)
@@ -520,7 +529,11 @@ make an initial adjustment of more than 1,000 seconds."
              (inetd-configuration
               (inherit config)
               (entries (append (inetd-configuration-entries config)
-                               entries)))))))
+                               entries)))))
+   (description
+    "Start @command{inetd}, the @dfn{Internet superserver}.  It is responsible
+for listening on Internet sockets and spawning the corresponding services on
+demand.")))
 
 \f
 ;;;
@@ -671,7 +684,10 @@ HiddenServicePort ~a ~a~%"
                            (hidden-services
                             (append (tor-configuration-hidden-services config)
                                     services)))))
-                (default-value (tor-configuration))))
+                (default-value (tor-configuration))
+                (description
+                 "Run the @uref{https://torproject.org, Tor} anonymous
+networking daemon.")))
 
 (define* (tor-service #:optional
                       (config-file (plain-file "empty" ""))
@@ -691,7 +707,9 @@ and lines for hidden services added via @code{tor-hidden-service}.  Run
   ;; A type that extends Tor with hidden services.
   (service-type (name 'tor-hidden-service)
                 (extensions
-                 (list (service-extension tor-service-type list)))))
+                 (list (service-extension tor-service-type list)))
+                (description
+                 "Define a new Tor @dfn{hidden service}.")))
 
 (define (tor-hidden-service name mapping)
   "Define a new Tor @dfn{hidden service} called @var{name} and implementing
@@ -798,7 +816,10 @@ project's documentation} for more information."
                                           (const %bitlbee-accounts))
                        (service-extension activation-service-type
                                           (const %bitlbee-activation))))
-                (default-value (bitlbee-configuration))))
+                (default-value (bitlbee-configuration))
+                (description
+                 "Run @url{http://bitlbee.org,BitlBee}, a daemon that acts as
+a gateway between IRC and chat networks.")))
 
 (define* (bitlbee-service #:key (bitlbee bitlbee)
                           (interface "127.0.0.1") (port 6667)
@@ -862,7 +883,10 @@ configuration file."
                                           (const %wicd-activation))
 
                        ;; Add Wicd to the global profile.
-                       (service-extension profile-service-type list)))))
+                       (service-extension profile-service-type list)))
+                (description
+                 "Run @url{https://launchpad.net/wicd,Wicd}, a network
+management daemon that aims to simplify wired and wireless networking.")))
 
 (define* (wicd-service #:key (wicd wicd))
   "Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network
@@ -931,7 +955,11 @@ dns=" dns "
                                (const %network-manager-activation))
             ;; Add network-manager to the system profile.
             (service-extension profile-service-type config->package)))
-     (default-value (network-manager-configuration)))))
+     (default-value (network-manager-configuration))
+     (description
+      "Run @uref{https://wiki.gnome.org/Projects/NetworkManager,
+NetworkManager}, a network management daemon that aims to simplify wired and
+wireless networking."))))
 
 \f
 ;;;
@@ -985,7 +1013,10 @@ dns=" dns "
                                             connman-activation)
                          ;; Add connman to the system profile.
                          (service-extension profile-service-type
-                                            connman-package))))))
+                                            connman-package)))
+                  (description
+                   "Run @url{https://01.org/connman,Connman},
+a network connection manager."))))
 
 \f
 ;;;
@@ -1071,6 +1102,10 @@ dns=" dns "
           (service-extension profile-service-type
                              (compose list openvswitch-configuration-package))
           (service-extension shepherd-root-service-type
-                             openvswitch-shepherd-service)))))
+                             openvswitch-shepherd-service)))
+   (description
+    "Run @uref{http://www.openvswitch.org, Open vSwitch}, a multilayer virtual
+switch designed to enable massive network automation through programmatic
+extension.")))
 
 ;;; networking.scm ends here
diff --git a/po/packages/POTFILES.in b/po/packages/POTFILES.in
index d111a6ffc..cfc542f50 100644
--- a/po/packages/POTFILES.in
+++ b/po/packages/POTFILES.in
@@ -58,3 +58,4 @@ gnu/packages/web.scm
 gnu/packages/wordnet.scm
 gnu/packages/xiph.scm
 gnu/services/base.scm
+gnu/services/networking.scm
-- 
2.14.1

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [bug#28452] [PATCH 0/6] On-line doc and search for services
  2017-09-13 21:17 [bug#28452] [PATCH 0/6] On-line doc and search for services Ludovic Courtès
  2017-09-13 21:24 ` [bug#28452] [PATCH 1/6] ui: Generalize relevance computation Ludovic Courtès
@ 2017-09-14  7:37 ` Christopher Baines
  2017-09-16 16:13   ` bug#28452: " Ludovic Courtès
  1 sibling, 1 reply; 9+ messages in thread
From: Christopher Baines @ 2017-09-14  7:37 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: 28452

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

On Wed, 13 Sep 2017 23:17:56 +0200
Ludovic Courtès <ludo@gnu.org> wrote:

> Hello!
> 
> This patch series adds a new ‘guix system search’ command to search
> through the available services types:
> 
> --8<---------------cut here---------------start------------->8---
> $ ./pre-inst-env guix system search anony network
> name: tor
> location: gnu/services/networking.scm:670:2
> extends: shepherd-root account activate
> description: Run the Tor (https://torproject.org) anonymous
> networking daemon. relevance: 9
> 
> name: static-networking
> location: gnu/services/networking.scm:248:2
> extends: shepherd-root etc
> description: Turn up the specified network interfaces upon startup,
> with the given IP
> + address, gateway, netmask, and so on.  The value for services of
> this type is a list of
> + `static-networking' objects, one per network interface.
> relevance: 6
> 
> name: network-manager
> location: gnu/services/networking.scm:947:4
> extends: shepherd-root dbus polkit activate profile
> description: Run NetworkManager
> (https://wiki.gnome.org/Projects/NetworkManager), a
> + network management daemon that aims to simplify wired and wireless
> networking. relevance: 6
> 
> [...]
> --8<---------------cut here---------------end--------------->8---
> 
> I think this can be pretty useful.  It also works with service types
> that have #f as their ‘description’ field, which is the vast majority
> of them (help welcome!).
> 
> Possible improvements and related things:
> 
>   • Display each field and value of the default value of services.
> 
>   • Add ‘guix system edit’ or ‘guix edit --service’?
> 
>   • Add a web UI to browse services.
> 
> Comments welcome!

This looks awesome Ludo :) I've tried it out locally, and it works
well. Obviously it will work a lot better when more services have
descriptions, but this is a great start.

I've also had a look through the patches, and they all look good to me.

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#28452: [PATCH 0/6] On-line doc and search for services
  2017-09-14  7:37 ` [bug#28452] [PATCH 0/6] On-line doc and search for services Christopher Baines
@ 2017-09-16 16:13   ` Ludovic Courtès
  0 siblings, 0 replies; 9+ messages in thread
From: Ludovic Courtès @ 2017-09-16 16:13 UTC (permalink / raw)
  To: Christopher Baines; +Cc: 28452-done

Hi Chris,

Christopher Baines <mail@cbaines.net> skribis:

> On Wed, 13 Sep 2017 23:17:56 +0200
> Ludovic Courtès <ludo@gnu.org> wrote:
>
>> Hello!
>> 
>> This patch series adds a new ‘guix system search’ command to search
>> through the available services types:

[...]

> This looks awesome Ludo :) I've tried it out locally, and it works
> well. Obviously it will work a lot better when more services have
> descriptions, but this is a great start.
>
> I've also had a look through the patches, and they all look good to me.

Thanks for your feedback!  I’ve pushed it now.

Note that this changes the ABI, so you’ll need at least:

  rm gnu/*.go gnu/services/*.go gnu/system/*.go && make

Ludo’.

^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2017-09-16 16:14 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2017-09-13 21:17 [bug#28452] [PATCH 0/6] On-line doc and search for services Ludovic Courtès
2017-09-13 21:24 ` [bug#28452] [PATCH 1/6] ui: Generalize relevance computation Ludovic Courtès
2017-09-13 21:24   ` [bug#28452] [PATCH 2/6] services: Add a description and location for each service type Ludovic Courtès
2017-09-13 21:24   ` [bug#28452] [PATCH 3/6] services: Add 'fold-service-types' Ludovic Courtès
2017-09-13 21:24   ` [bug#28452] [PATCH 4/6] guix system: Add 'search' command Ludovic Courtès
2017-09-13 21:24   ` [bug#28452] [PATCH 5/6] services: base: Add descriptions Ludovic Courtès
2017-09-13 21:24   ` [bug#28452] [PATCH 6/6] services: networking: " Ludovic Courtès
2017-09-14  7:37 ` [bug#28452] [PATCH 0/6] On-line doc and search for services Christopher Baines
2017-09-16 16:13   ` bug#28452: " Ludovic Courtès

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/guix.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.