* [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 public inbox
https://git.savannah.gnu.org/cgit/guix.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).