aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/build.scm180
-rw-r--r--doc/guix-cookbook.texi137
-rw-r--r--doc/guix.texi483
-rw-r--r--doc/local.mk19
-rw-r--r--doc/package-hello.json31
5 files changed, 661 insertions, 189 deletions
diff --git a/doc/build.scm b/doc/build.scm
index 8d5b58962a..3907b49caf 100644
--- a/doc/build.scm
+++ b/doc/build.scm
@@ -142,7 +142,7 @@ as well as images, OS examples, and translations."
(for-each (lambda (texi)
(install-file texi #$output))
- (append (find-files #$documentation "\\.(texi|scm)$")
+ (append (find-files #$documentation "\\.(texi|scm|json)$")
(find-files #$(translated-texi-manuals source)
"\\.texi$")))
@@ -220,8 +220,11 @@ its <pre class=\"lisp\"> blocks (as produced by 'makeinfo --html')."
(syntax-highlight scheme)
(syntax-highlight lexers)
(guix build utils)
+ (srfi srfi-1)
+ (srfi srfi-26)
(ice-9 match)
- (ice-9 threads))
+ (ice-9 threads)
+ (ice-9 vlist))
(define (pair-open/close lst)
;; Pair 'open' and 'close' tags produced by 'highlights' and
@@ -255,10 +258,11 @@ its <pre class=\"lisp\"> blocks (as produced by 'makeinfo --html')."
level (reverse result)))
(values (reverse result) "" '())))))
- (define (highlights->sxml* highlights)
+ (define (highlights->sxml* highlights anchors)
;; Like 'highlights->sxml', but handle nested 'paren tags. This
;; allows for paren matching highlights via appropriate CSS
- ;; "hover" properties.
+ ;; "hover" properties. When a symbol is encountered, look it up
+ ;; in ANCHORS, a vhash, and emit the corresponding href, if any.
(define (tag->class tag)
(string-append "syntax-" (symbol->string tag)))
@@ -269,8 +273,16 @@ its <pre class=\"lisp\"> blocks (as produced by 'makeinfo --html')."
(number->string level))))
,open
(span (@ (class "syntax-symbol"))
- ,@(highlights->sxml* body))
+ ,@(highlights->sxml* body anchors))
,close))
+ (('symbol text)
+ ;; Check whether we can emit a hyperlink for TEXT.
+ (match (vhash-assoc text anchors)
+ (#f
+ `(span (@ (class ,(tag->class 'symbol))) ,text))
+ ((_ . target)
+ `(a (@ (class ,(tag->class 'symbol)) (href ,target))
+ ,text))))
((tag text)
`(span (@ (class ,(tag->class tag))) ,text)))
highlights))
@@ -301,35 +313,109 @@ its <pre class=\"lisp\"> blocks (as produced by 'makeinfo --html')."
(pk 'unsupported-code-snippet something)
(primitive-exit 1)))))
- (define (syntax-highlight sxml)
+ (define (syntax-highlight sxml anchors)
;; Recurse over SXML and syntax-highlight code snippets.
- (match sxml
- (('*TOP* decl body ...)
- `(*TOP* ,decl ,@(map syntax-highlight body)))
- (('head things ...)
- `(head ,@things
- (link (@ (rel "stylesheet")
- (type "text/css")
- (href #$syntax-css-url)))))
- (('pre ('@ ('class "lisp")) code-snippet ...)
- `(pre (@ (class "lisp"))
- ,@(highlights->sxml*
- (pair-open/close
- (highlight lex-scheme
- (concatenate-snippets code-snippet))))))
- ((tag ('@ attributes ...) body ...)
- `(,tag (@ ,@attributes) ,@(map syntax-highlight body)))
- ((tag body ...)
- `(,tag ,@(map syntax-highlight body)))
- ((? string? str)
- str)))
-
- (define (process-html file)
+ (let loop ((sxml sxml))
+ (match sxml
+ (('*TOP* decl body ...)
+ `(*TOP* ,decl ,@(map loop body)))
+ (('head things ...)
+ `(head ,@things
+ (link (@ (rel "stylesheet")
+ (type "text/css")
+ (href #$syntax-css-url)))))
+ (('pre ('@ ('class "lisp")) code-snippet ...)
+ `(pre (@ (class "lisp"))
+ ,@(highlights->sxml*
+ (pair-open/close
+ (highlight lex-scheme
+ (concatenate-snippets code-snippet)))
+ anchors)))
+ ((tag ('@ attributes ...) body ...)
+ `(,tag (@ ,@attributes) ,@(map loop body)))
+ ((tag body ...)
+ `(,tag ,@(map loop body)))
+ ((? string? str)
+ str))))
+
+ (define (underscore-decode str)
+ ;; Decode STR, an "underscore-encoded" string as produced by
+ ;; makeinfo for indexes, such as "_0025base_002dservices" for
+ ;; "%base-services".
+ (let loop ((str str)
+ (result '()))
+ (match (string-index str #\_)
+ (#f
+ (string-concatenate-reverse (cons str result)))
+ (index
+ (let ((char (string->number
+ (substring str (+ index 1) (+ index 5))
+ 16)))
+ (loop (string-drop str (+ index 5))
+ (append (list (string (integer->char char))
+ (string-take str index))
+ result)))))))
+
+ (define (anchor-id->key id)
+ ;; Convert ID, an anchor ID such as
+ ;; "index-pam_002dlimits_002dservice" to the corresponding key,
+ ;; "pam-limits-service" in this example. Drop the suffix of
+ ;; duplicate anchor IDs like "operating_002dsystem-1".
+ (let ((id (if (any (cut string-suffix? <> id)
+ '("-1" "-2" "-3" "-4" "-5"))
+ (string-drop-right id 2)
+ id)))
+ (underscore-decode
+ (string-drop id (string-length "index-")))))
+
+ (define* (collect-anchors file #:optional (vhash vlist-null))
+ ;; Collect the anchors that appear in FILE, a makeinfo-generated
+ ;; file. Grab those from <dt> tags, which corresponds to
+ ;; Texinfo @deftp, @defvr, etc. Return VHASH augmented with
+ ;; more name/reference pairs.
+ (define string-or-entity?
+ (match-lambda
+ ((? string?) #t)
+ (('*ENTITY* _ ...) #t)
+ (_ #f)))
+
+ (define (worthy-entry? lst)
+ ;; Attempt to match:
+ ;; Scheme Variable: <strong>x</strong>
+ ;; but not:
+ ;; <code>cups-configuration</code> parameter: …
+ (let loop ((lst lst))
+ (match lst
+ (((? string-or-entity?) rest ...)
+ (loop rest))
+ ((('strong _ ...) _ ...)
+ #t)
+ (_ #f))))
+
+ (let ((shtml (call-with-input-file file html->shtml)))
+ (let loop ((shtml shtml)
+ (vhash vhash))
+ (match shtml
+ (('dt ('@ ('id id)) rest ...)
+ (if (and (string-prefix? "index-" id)
+ (worthy-entry? rest))
+ (vhash-cons (anchor-id->key id)
+ (string-append (basename file)
+ "#" id)
+ vhash)
+ vhash))
+ ((tag ('@ _ ...) body ...)
+ (fold loop vhash body))
+ ((tag body ...)
+ (fold loop vhash body))
+ (_ vhash)))))
+
+ (define (process-html file anchors)
;; Parse FILE and perform syntax highlighting for its Scheme
;; snippets. Install the result to #$output.
(format (current-error-port) "processing ~a...~%" file)
(let* ((shtml (call-with-input-file file html->shtml))
- (highlighted (syntax-highlight shtml))
+ (highlighted (syntax-highlight shtml anchors))
(base (string-drop file (string-length #$input)))
(target (string-append #$output base)))
(mkdir-p (dirname target))
@@ -352,17 +438,43 @@ its <pre class=\"lisp\"> blocks (as produced by 'makeinfo --html')."
(pk 'error-link file target (strerror errno))
(primitive-exit 3))))))
+ (define (html? file stat)
+ (string-suffix? ".html" file))
+
;; Install a UTF-8 locale so we can process UTF-8 files.
(setenv "GUIX_LOCPATH"
#+(file-append glibc-utf8-locales "/lib/locale"))
(setlocale LC_ALL "en_US.utf8")
+ ;; First process the mono-node 'guix.html' files.
(n-par-for-each (parallel-job-count)
- (lambda (file)
- (if (string-suffix? ".html" file)
- (process-html file)
- (copy-as-is file)))
- (find-files #$input))))))
+ (lambda (mono)
+ (let ((anchors (collect-anchors mono)))
+ (process-html mono anchors)))
+ (find-files #$input "^guix(\\.[a-zA-Z_-]+)?\\.html$"))
+
+ ;; Next process the multi-node HTML files in two phases: (1)
+ ;; collect the list of anchors, and (2) perform
+ ;; syntax-highlighting.
+ (let* ((multi (find-files #$input "^html_node$"
+ #:directories? #t))
+ (anchors (n-par-map (parallel-job-count)
+ (lambda (multi)
+ (cons multi
+ (fold collect-anchors vlist-null
+ (find-files multi html?))))
+ multi)))
+ (n-par-for-each (parallel-job-count)
+ (lambda (file)
+ (let ((anchors (assoc-ref anchors (dirname file))))
+ (process-html file anchors)))
+ (append-map (lambda (multi)
+ (find-files multi html?))
+ multi)))
+
+ ;; Last, copy non-HTML files as is.
+ (for-each copy-as-is
+ (find-files #$input (negate html?)))))))
(computed-file name build))
diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index 477b7e3dff..82700a48ad 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -11,6 +11,8 @@
Copyright @copyright{} 2019 Ricardo Wurmus@*
Copyright @copyright{} 2019 Efraim Flashner@*
Copyright @copyright{} 2019 Pierre Neidhardt@*
+Copyright @copyright{} 2020 Oleg Pykhalov@*
+Copyright @copyright{} 2020 Matthew Brooks@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -579,7 +581,7 @@ packages.
Guix makes it possible to streamline the process by adding as many ``package
declaration directories'' as you want.
-Create a directory, say @samp{~./guix-packages} and add it to the @samp{GUIX_PACKAGE_PATH}
+Create a directory, say @file{~./guix-packages} and add it to the @samp{GUIX_PACKAGE_PATH}
environment variable:
@example
@@ -849,7 +851,7 @@ version when packaging programs for a specific commit.
@subsubsection Snippets
Snippets are quoted (i.e. non-evaluated) Scheme code that are a means of patching
-the source. They are a Guix-y alternative to the traditional @samp{.patch} files.
+the source. They are a Guix-y alternative to the traditional @file{.patch} files.
Because of the quote, the code in only evaluated when passed to the Guix daemon
for building. There can be as many snippets as needed.
@@ -953,7 +955,7 @@ $ make CC=gcc prefix=/gnu/store/...-<out>
This sets the C compiler to @code{gcc} and the @code{prefix} variable (the installation
directory in Make parlance) to @code{(assoc-ref %outputs "out")}, which is a build-stage
global variable pointing to the destination directory in the store (something like
-@samp{/gnu/store/...-my-libgit2-20180408}).
+@file{/gnu/store/...-my-libgit2-20180408}).
Similarly, it's possible to set the configure flags:
@@ -1078,7 +1080,7 @@ mechanism of passing code around two running processes is called @uref{https://a
@subsubsection Utility functions
When customizing @code{phases}, we often need to write code that mimics the
-equivalent system invocations (@code{make}, @code{mkdir}, @code{cp}, etc.) commonly used during
+equivalent system invocations (@code{make}, @code{mkdir}, @code{cp}, etc.)@: commonly used during
regular ``Unix-style'' installations.
Some like @code{chmod} are native to Guile.
@@ -1319,7 +1321,9 @@ chapter is to demonstrate some advanced configuration concepts.
reference.
@menu
-* Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System.
+* Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System.
+* Customizing a Window Manager:: Handle customization of a Window manager on Guix System.
+* Setting up a bind mount:: Setting up a bind mount in the file-systems definition.
@end menu
@node Customizing the Kernel
@@ -1562,6 +1566,105 @@ likely that you'll need to modify the initrd on a machine using a custom
kernel, since certain modules which are expected to be built may not be
available for inclusion into the initrd.
+@node Customizing a Window Manager
+@section Customizing a Window Manager
+@cindex wm
+
+@node StumpWM
+@subsection StumpWM
+@cindex stumpwm
+
+You could install StumpWM with a Guix system by adding
+@code{stumpwm-checkout} and optionally @code{`(,stumpwm-checkout "lib")}
+packages to a system configuration file, e.g.@: @file{/etc/config.scm}.
+
+An example configuration can look like this:
+
+@lisp
+(use-modules (gnu))
+(use-package-modules wm)
+
+(operating-system
+ ;; …
+ (packages (append (list sbcl stumpwm-checkout `(,stumpwm-checkout "lib"))
+ %base-packages)))
+@end lisp
+
+@cindex stumpwm fonts
+By default StumpWM uses X11 fonts, which could be small or pixelated on
+your system. You could fix this by installing StumpWM contrib Lisp
+module @code{sbcl-stumpwm-ttf-fonts}, adding it to Guix system packages:
+
+@lisp
+(use-modules (gnu))
+(use-package-modules fonts wm)
+
+(operating-system
+ ;; …
+ (packages (append (list sbcl stumpwm-checkout `(,stumpwm-checkout "lib"))
+ sbcl-stumpwm-ttf-fonts font-dejavu %base-packages)))
+@end lisp
+
+Then you need to add the following code to a StumpWM configuration file
+@file{~/.stumpwm.d/init.lisp}:
+
+@lisp
+(require :ttf-fonts)
+(setf xft:*font-dirs* '("/run/current-system/profile/share/fonts/"))
+(setf clx-truetype:+font-cache-filename+ (concat (getenv "HOME") "/.fonts/font-cache.sexp"))
+(xft:cache-fonts)
+(set-font (make-instance 'xft:font :family "DejaVu Sans Mono" :subfamily "Book" :size 11))
+@end lisp
+
+@node Setting up a bind mount
+@section Setting up a bind mount
+
+To bind mount a file system, one must first set up some definitions
+before the @code{operating-system} section of the system definition. In
+this example we will bind mount a folder from a spinning disk drive to
+@file{/tmp}, to save wear and tear on the primary SSD, without
+dedicating an entire partition to be mounted as @file{/tmp}.
+
+First, the source drive that hosts the folder we wish to bind mount
+should be defined, so that the bind mount can depend on it.
+
+@lisp
+(define source-drive ;; "source-drive" can be named anything you want.
+ (file-system
+ (device (uuid "UUID goes here"))
+ (mount-point "/path-to-spinning-disk-goes-here")
+ (type "ext4"))) ;; Make sure to set this to the appropriate type for your drive.
+@end lisp
+
+The source folder must also be defined, so that guix will know it's not
+a regular block device, but a folder.
+@lisp
+(define (%source-directory) "/path-to-spinning-disk-goes-here/tmp") ;; "source-directory" can be named any valid variable name.
+@end lisp
+
+Finally, inside the @code{file-systems} definition, we must add the
+mount itself.
+
+@lisp
+(file-systems (cons*
+
+ ...<other drives omitted for clarity>...
+
+ source-drive ;; Must match the name you gave the source drive in the earlier definition.
+
+ (file-system
+ (device (%source-directory)) ;; Make sure "source-directory" matches your earlier definition.
+ (mount-point "/tmp")
+ (type "none") ;; We are mounting a folder, not a partition, so this type needs to be "none"
+ (flags '(bind-mount))
+ (dependencies (list source-drive)) ;; Ensure "source-drive" matches what you've named the variable for the drive.
+ )
+
+ ...<other drives omitted for clarity>...
+
+ ))
+@end lisp
+
@c *********************************************************************
@node Advanced package management
@chapter Advanced package management
@@ -1688,8 +1791,8 @@ where we will store our profiles in the rest of this article.
Placing all your profiles in a single directory, with each profile getting its
own sub-directory, is somewhat cleaner. This way, each sub-directory will
-contain all the symlinks for precisely one profile. Besides, "looping over
-profiles" becomes obvious from any programming language (e.g. a shell script) by
+contain all the symlinks for precisely one profile. Besides, ``looping over
+profiles'' becomes obvious from any programming language (e.g.@: a shell script) by
simply looping over the sub-directories of @samp{$GUIX_EXTRA_PROFILES}.
Note that it's also possible to loop over the output of
@@ -1698,9 +1801,9 @@ Note that it's also possible to loop over the output of
guix package --list-profiles
@end example
-although you'll probably have to filter out @samp{~/.config/guix/current}.
+although you'll probably have to filter out @file{~/.config/guix/current}.
-To enable all profiles on login, add this to your @samp{~/.bash_profile} (or similar):
+To enable all profiles on login, add this to your @file{~/.bash_profile} (or similar):
@example
for i in $GUIX_EXTRA_PROFILES/*; do
@@ -1714,8 +1817,8 @@ done
@end example
Note to Guix System users: the above reflects how your default profile
-@samp{~/.guix-profile} is activated from @samp{/etc/profile}, that latter being loaded by
-@samp{~/.bashrc} by default.
+@file{~/.guix-profile} is activated from @file{/etc/profile}, that latter being loaded by
+@file{~/.bashrc} by default.
You can obviously choose to only enable a subset of them:
@@ -1758,8 +1861,8 @@ guix package -m /path/to/guix-my-project-manifest.scm -p "$GUIX_EXTRA_PROFILES"/
To upgrade all profiles, it's easy enough to loop over them. For instance,
assuming your manifest specifications are stored in
-@samp{~/.guix-manifests/guix-$profile-manifest.scm}, with @samp{$profile} being the name
-of the profile (e.g. "project1"), you could do the following in Bourne shell:
+@file{~/.guix-manifests/guix-$profile-manifest.scm}, with @samp{$profile} being the name
+of the profile (e.g.@: "project1"), you could do the following in Bourne shell:
@example
for profile in "$GUIX_EXTRA_PROFILES"/*; do
@@ -1818,12 +1921,12 @@ The same is true for @samp{INFOPATH} (you can install @samp{info-reader}),
@node Default profile
@subsection Default profile
-What about the default profile that Guix keeps in @samp{~/.guix-profile}?
+What about the default profile that Guix keeps in @file{~/.guix-profile}?
You can assign it the role you want. Typically you would install the manifest
of the packages you want to use all the time.
-Alternatively, you could keep it "manifest-less" for throw-away packages
+Alternatively, you could keep it ``manifest-less'' for throw-away packages
that you would just use for a couple of days.
This way makes it convenient to run
@@ -1854,7 +1957,7 @@ Manifests come with multiple benefits. In particular, they ease maintenance:
@itemize
@item
When a profile is set up from a manifest, the manifest itself is
-self-sufficient to keep a "package listing" around and reinstall the profile
+self-sufficient to keep a ``package listing'' around and reinstall the profile
later or on a different system. For ad-hoc profiles, we would need to
generate a manifest specification manually and maintain the package versions
for the packages that don't use the default version.
@@ -1891,7 +1994,7 @@ They can be manipulated in Scheme and passed to the various Guix @uref{https://e
It's important to understand that while manifests can be used to declare
profiles, they are not strictly equivalent: profiles have the side effect that
-they "pin" packages in the store, which prevents them from being
+they ``pin'' packages in the store, which prevents them from being
garbage-collected (@pxref{Invoking guix gc,,, guix, GNU Guix Reference Manual})
and ensures that they will still be available at any point in
the future.
diff --git a/doc/guix.texi b/doc/guix.texi
index 8cb85fe62c..d0592220a7 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -63,7 +63,7 @@ Copyright @copyright{} 2018, 2019 Florian Pelz@*
Copyright @copyright{} 2018 Laura Lazzati@*
Copyright @copyright{} 2018 Alex Vong@*
Copyright @copyright{} 2019 Josh Holland@*
-Copyright @copyright{} 2019 Diego Nicola Barbato@*
+Copyright @copyright{} 2019, 2020 Diego Nicola Barbato@*
Copyright @copyright{} 2019 Ivan Petkov@*
Copyright @copyright{} 2019 Jakob L. Kreuze@*
Copyright @copyright{} 2019 Kyle Andrews@*
@@ -76,6 +76,8 @@ Copyright @copyright{} 2020 Damien Cassou@*
Copyright @copyright{} 2020 Jakub Kądziołka@*
Copyright @copyright{} 2020 Jack Hill@*
Copyright @copyright{} 2020 Naga Malleswari@*
+Copyright @copyright{} 2020 Brice Waegeneire@*
+Copyright @copyright{} 2020 R Veera Kumar@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -546,7 +548,14 @@ We recommend the use of this
@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
shell installer script}. The script automates the download, installation, and
initial configuration steps described below. It should be run as the root
-user.
+user. As root, you can thus run this:
+
+@example
+cd /tmp
+wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
+chmod +x guix-install.sh
+./guix-install.sh
+@end example
@end quotation
Installing goes along these lines:
@@ -650,7 +659,7 @@ with these commands:
@example
# cp ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
/etc/systemd/system/
-# systemctl start guix-daemon && systemctl enable guix-daemon
+# systemctl enable --now guix-daemon
@end example
If your host distro uses the Upstart init system:
@@ -1682,7 +1691,18 @@ package in Guix looks for fonts in @file{$HOME/.guix-profile}
by default. Thus, to allow graphical applications installed with Guix
to display fonts, you have to install fonts with Guix as well.
Essential font packages include @code{gs-fonts}, @code{font-dejavu}, and
-@code{font-gnu-freefont-ttf}.
+@code{font-gnu-freefont}.
+
+@cindex @code{fc-cache}
+@cindex font cache
+Once you have installed or removed fonts, or when you notice an
+application that does not find fonts, you may need to install Fontconfig
+and to force an update of its font cache by running:
+
+@example
+guix install fontconfig
+fc-cache -rv
+@end example
To display text written in Chinese languages, Japanese, or Korean in
graphical applications, consider installing
@@ -1717,13 +1737,6 @@ xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir)
After that, you can run @code{xlsfonts} (from @code{xlsfonts} package)
to make sure your TrueType fonts are listed there.
-@cindex @code{fc-cache}
-@cindex font cache
-After installing fonts you may have to refresh the font cache to use
-them in applications. The same applies when applications installed via
-Guix do not seem to find fonts. To force rebuilding of the font cache
-run @code{fc-cache -rv}. The @code{fc-cache} command is provided by
-the @code{fontconfig} package.
@subsection X.509 Certificates
@@ -2198,6 +2211,18 @@ ping -c 3 gnu.org
Setting up network access is almost always a requirement because the
image does not contain all the software and tools that may be needed.
+@cindex proxy, during system installation
+If you need HTTP and HTTPS access to go through a proxy, run the
+following command:
+
+@example
+herd set-http-proxy guix-daemon @var{URL}
+@end example
+
+@noindent
+where @var{URL} is the proxy URL, for example
+@code{http://example.org:8118}.
+
@cindex installing over SSH
If you want to, you can continue the installation remotely by starting
an SSH server:
@@ -2806,6 +2831,15 @@ in the root of their project source tree that can be used to test
development snapshots and create reproducible development environments
(@pxref{Invoking guix environment}).
+The @var{file} may also contain a JSON representation of one or more
+package definitions. Running @code{guix package -f} on
+@file{hello.json} with the following contents would result in installing
+the package @code{greeter} after building @code{myhello}:
+
+@example
+@verbatiminclude package-hello.json
+@end example
+
@item --remove=@var{package} @dots{}
@itemx -r @var{package} @dots{}
Remove the specified @var{package}s.
@@ -4599,8 +4633,8 @@ served by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}:
@example
$ wget -O - \
- https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-emacs-24.5 \
- | bunzip2 | guix archive -x /tmp/emacs
+ https://@value{SUBSTITUTE-SERVER}/nar/gzip/@dots{}-emacs-24.5 \
+ | gunzip | guix archive -x /tmp/emacs
@end example
Single-item archives are different from multiple-item archives produced
@@ -4610,7 +4644,8 @@ and they do @emph{not} embed a signature. Thus this operation does
unsafe.
The primary purpose of this operation is to facilitate inspection of
-archive contents coming from possibly untrusted substitute servers.
+archive contents coming from possibly untrusted substitute servers
+(@pxref{Invoking guix challenge}).
@item --list
@itemx -t
@@ -5083,7 +5118,7 @@ guix pack -f squashfs bash guile emacs geiser
@noindent
The result is a SquashFS file system image that can either be mounted or
directly be used as a file system container image with the
-@uref{https://singularity.lbl.gov, Singularity container execution
+@uref{https://www.sylabs.io/docs/, Singularity container execution
environment}, using commands like @command{singularity shell} or
@command{singularity exec}.
@@ -5790,7 +5825,7 @@ or a list of such values.
@item @code{home-page}
The URL to the home-page of the package, as a string.
-@item @code{supported-systems} (default: @var{%supported-systems})
+@item @code{supported-systems} (default: @code{%supported-systems})
The list of systems supported by the package, as strings of the form
@code{architecture-kernel}, for example @code{"x86_64-linux"}.
@@ -6064,8 +6099,8 @@ implements a build procedure for Android NDK (native development kit)
packages using a Guix-specific build process.
The build system assumes that packages install their public interface
-(header) files to the subdirectory "include" of the "out" output and
-their libraries to the subdirectory "lib" of the "out" output.
+(header) files to the subdirectory @file{include} of the @code{out} output and
+their libraries to the subdirectory @file{lib} the @code{out} output.
It's also assumed that the union of all the dependencies of a package
has no conflicting files.
@@ -6154,7 +6189,6 @@ if they are defined by the crate.
@defvr {Scheme Variable} copy-build-system
-@cindex (copy build system)
This variable is exported by @code{(guix build-system copy)}. It
supports builds of simple packages that don't require much compiling,
mostly just moving files around.
@@ -6768,8 +6802,8 @@ kernel module.
@end table
It is possible and useful to specify the Linux kernel to use for building
-the module (in the "arguments" form of a package using the
-linux-module-build-system, use the key #:linux to specify it).
+the module (in the @code{arguments} form of a package using the
+@code{linux-module-build-system}, use the key @code{#:linux} to specify it).
@end defvr
@defvr {Scheme Variable} node-build-system
@@ -7354,7 +7388,7 @@ increments the current state value:
@result{} 3
@end lisp
-When ``run'' through @var{%state-monad}, we obtain that additional state
+When ``run'' through @code{%state-monad}, we obtain that additional state
value, which is the number of @code{square} calls.
@end defvr
@@ -7386,7 +7420,7 @@ The main interface to the store monad, provided by the @code{(guix
store)} module, is as follows.
@defvr {Scheme Variable} %store-monad
-The store monad---an alias for @var{%state-monad}.
+The store monad---an alias for @code{%state-monad}.
Values in the store monad encapsulate accesses to the store. When its
effect is needed, a value of the store monad must be ``evaluated'' by
@@ -7449,6 +7483,10 @@ value in the absolute file name of @var{file} within the @var{output}
directory of @var{package}. When @var{file} is omitted, return the name
of the @var{output} directory of @var{package}. When @var{target} is
true, use it as a cross-compilation target triplet.
+
+Note that this procedure does @emph{not} build @var{package}. Thus, the
+result might or might not designate an existing file. We recommend not
+using this procedure unless you know what you are doing.
@end deffn
@deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
@@ -7747,7 +7785,7 @@ information about monads.)
[#:system (%current-system)] [#:target #f] [#:graft? #t] @
[#:hash #f] [#:hash-algo #f] @
[#:recursive? #f] [#:env-vars '()] [#:modules '()] @
- [#:module-path @var{%load-path}] @
+ [#:module-path @code{%load-path}] @
[#:effective-version "2.2"] @
[#:references-graphs #f] [#:allowed-references #f] @
[#:disallowed-references #f] @
@@ -7917,7 +7955,8 @@ The resulting file holds references to all the dependencies of @var{exp}
or a subset thereof.
@end deffn
-@deffn {Scheme Procedure} scheme-file @var{name} @var{exp} [#:splice? #f]
+@deffn {Scheme Procedure} scheme-file @var{name} @var{exp} @
+ [#:splice? #f] [#:set-load-path? #t]
Return an object representing the Scheme file @var{name} that contains
@var{exp}.
@@ -8051,7 +8090,7 @@ item. This is achieved using the @code{lower-object} monadic procedure.
@deffn {Monadic Procedure} lower-object @var{obj} [@var{system}] @
[#:target #f]
-Return as a value in @var{%store-monad} the derivation or store item
+Return as a value in @code{%store-monad} the derivation or store item
corresponding to @var{obj} for @var{system}, cross-compiling for
@var{target} if @var{target} is true. @var{obj} must be an object that
has an associated gexp compiler, such as a @code{<package>}.
@@ -8533,6 +8572,15 @@ As an example, @var{file} might contain a package definition like this
@include package-hello.scm
@end lisp
+The @var{file} may also contain a JSON representation of one or more
+package definitions. Running @code{guix build -f} on @file{hello.json}
+with the following contents would result in building the packages
+@code{myhello} and @code{greeter}:
+
+@example
+@verbatiminclude package-hello.json
+@end example
+
@item --manifest=@var{manifest}
@itemx -m @var{manifest}
Build all packages listed in the given @var{manifest}
@@ -8782,7 +8830,7 @@ $ guix environment --no-grafts -C foo --ad-hoc strace gdb
Here, @command{guix environment -C} creates a container and spawns a new
shell in it (@pxref{Invoking guix environment}). The @command{--ad-hoc
strace gdb} part adds the @command{strace} and @command{gdb} commands to
-the container, which would may find handy while debugging. The
+the container, which you may find handy while debugging. The
@option{--no-grafts} option makes sure we get the exact same
environment, with ungrafted packages (@pxref{Security Updates}, for more
info on grafts).
@@ -10538,8 +10586,8 @@ Alternately, we can do something along these lines (@pxref{Invoking guix
archive}):
@example
-$ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0 \
- | guix archive -x /tmp/git
+$ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-git-2.5.0 \
+ | lzip -d | guix archive -x /tmp/git
$ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
@end example
@@ -11217,7 +11265,7 @@ By that, we mean all the global system configuration, not per-user
configuration (@pxref{Using the Configuration System}).
@table @asis
-@item @code{kernel} (default: @var{linux-libre})
+@item @code{kernel} (default: @code{linux-libre})
The package object of the operating system kernel to use@footnote{Currently
only the Linux-libre kernel is supported. In the future, it will be
possible to use the GNU@tie{}Hurd.}.
@@ -11374,11 +11422,11 @@ As a user you should @emph{never} need to touch this field.
Linux @dfn{pluggable authentication module} (PAM) services.
@c FIXME: Add xref to PAM services section.
-@item @code{setuid-programs} (default: @var{%setuid-programs})
+@item @code{setuid-programs} (default: @code{%setuid-programs})
List of string-valued G-expressions denoting setuid programs.
@xref{Setuid Programs}.
-@item @code{sudoers-file} (default: @var{%sudoers-specification})
+@item @code{sudoers-file} (default: @code{%sudoers-specification})
@cindex sudoers file
The contents of the @file{/etc/sudoers} file as a file-like object
(@pxref{G-Expressions, @code{local-file} and @code{plain-file}}).
@@ -11544,7 +11592,7 @@ variables.
@defvr {Scheme Variable} %base-file-systems
These are essential file systems that are required on normal systems,
-such as @var{%pseudo-terminal-file-system} and @var{%immutable-store} (see
+such as @code{%pseudo-terminal-file-system} and @code{%immutable-store} (see
below.) Operating system declarations should always contain at least
these.
@end defvr
@@ -11915,6 +11963,9 @@ about. Here are a few example:
;; The Catalan layout.
(keyboard-layout "es" "cat")
+;; Arabic layout with "Alt-Shift" to switch to US layout.
+(keyboard-layout "ar,us" #:options '("grp:alt_shift_toggle"))
+
;; The Latin American Spanish layout. In addition, the
;; "Caps Lock" key is used as an additional "Ctrl" key,
;; and the "Menu" key is used as a "Compose" key to enter
@@ -12376,7 +12427,7 @@ man page for more information.
@item @code{tty}
The name of the console this agetty runs on, as a string---e.g.,
-@code{"ttyS0"}. This argument is optional, it will default to
+@code{"ttyS0"}. This argument is optional, it will default to
a reasonable default serial port used by the kernel Linux.
For this, if there is a value for an option @code{agetty.tty} in the kernel
@@ -12411,7 +12462,7 @@ in automatically without prompting for their login name or password.
When @code{#t}, don't reset terminal cflags (control modes).
@item @code{host} (default: @code{#f})
-This accepts a string containing the "login_host", which will be written
+This accepts a string containing the ``login_host'', which will be written
into the @file{/var/run/utmpx} file.
@item @code{remote?} (default: @code{#f})
@@ -12517,8 +12568,8 @@ This option accepts a string of additional characters that should be
interpreted as backspace when the user types their login name.
@item @code{kill-characters} (default: @code{#f})
-This option accepts a string that should be interpreted to mean "ignore
-all previous characters" (also called a "kill" character) when the user
+This option accepts a string that should be interpreted to mean ``ignore
+all previous characters'' (also called a ``kill'' character) when the user
types their login name.
@item @code{chdir} (default: @code{#f})
@@ -12534,7 +12585,7 @@ This option accepts, as an integer, the nice value with which to run the
@command{login} program.
@item @code{extra-options} (default: @code{'()})
-This option provides an "escape hatch" for the user to provide arbitrary
+This option provides an ``escape hatch'' for the user to provide arbitrary
command-line arguments to @command{agetty} as a list of strings.
@end table
@@ -12608,7 +12659,7 @@ and caches.
@defvr {Scheme Variable} %nscd-default-configuration
This is the default @code{<nscd-configuration>} value (see below) used
by @code{nscd-service}. It uses the caches defined by
-@var{%nscd-default-caches}; see below.
+@code{%nscd-default-caches}; see below.
@end defvr
@deftp {Data Type} nscd-configuration
@@ -12633,7 +12684,7 @@ Name of the nscd log file. This is where debugging output goes when
Integer denoting the debugging levels. Higher numbers mean that more
debugging output is logged.
-@item @code{caches} (default: @var{%nscd-default-caches})
+@item @code{caches} (default: @code{%nscd-default-caches})
List of @code{<nscd-cache>} objects denoting things to be cached; see
below.
@@ -12771,9 +12822,24 @@ List of extra command-line options for @command{guix-daemon}.
File where @command{guix-daemon}'s standard output and standard error
are written.
+@cindex HTTP proxy, for @code{guix-daemon}
+@cindex proxy, for @code{guix-daemon} HTTP access
@item @code{http-proxy} (default: @code{#f})
-The HTTP proxy used for downloading fixed-output derivations and
-substitutes.
+The URL of the HTTP and HTTPS proxy used for downloading fixed-output
+derivations and substitutes.
+
+It is also possible to change the daemon's proxy at run time through the
+@code{set-http-proxy} action, which restarts it:
+
+@example
+herd set-http-proxy guix-daemon http://localhost:8118
+@end example
+
+To clear the proxy settings, run:
+
+@example
+herd set-http-proxy guix-daemon
+@end example
@item @code{tmpdir} (default: @code{#f})
A directory path where the @command{guix-daemon} will perform builds.
@@ -12784,8 +12850,12 @@ A directory path where the @command{guix-daemon} will perform builds.
@deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}]
Run @var{udev}, which populates the @file{/dev} directory dynamically.
udev rules can be provided as a list of files through the @var{rules}
-variable. The procedures @code{udev-rule} and @code{file->udev-rule} from
-@code{(gnu services base)} simplify the creation of such rule files.
+variable. The procedures @code{udev-rule}, @code{udev-rules-service}
+and @code{file->udev-rule} from @code{(gnu services base)} simplify the
+creation of such rule files.
+
+The @command{herd rules udev} command, as root, returns the name of the
+directory containing all the active udev rules.
@end deffn
@deffn {Scheme Procedure} udev-rule [@var{file-name} @var{contents}]
@@ -12804,23 +12874,27 @@ upon detecting a USB device with a given product identifier.
"ATTR@{product@}==\"Example\", "
"RUN+=\"/path/to/script\"")))
@end lisp
-
-The @command{herd rules udev} command, as root, returns the name of the
-directory containing all the active udev rules.
@end deffn
-Here we show how the default @var{udev-service} can be extended with it.
+@deffn {Scheme Procedure} udev-rules-service [@var{name} @var{rules}] @
+ [#:groups @var{groups}]
+Return a service that extends @code{udev-service-type } with @var{rules}
+and @code{account-service-type} with @var{groups} as system groups.
+This works by creating a singleton service type
+@code{@var{name}-udev-rules}, of which the returned service is an
+instance.
+
+Here we show how it can be used to extend @code{udev-service-type} with the
+previously defined rule @code{%example-udev-rule}.
@lisp
(operating-system
;; @dots{}
(services
- (modify-services %desktop-services
- (udev-service-type config =>
- (udev-configuration (inherit config)
- (rules (append (udev-configuration-rules config)
- (list %example-udev-rule))))))))
+ (cons (udev-rules-service 'usb-thing %example-udev-rule)
+ %desktop-services)))
@end lisp
+@end deffn
@deffn {Scheme Procedure} file->udev-rule [@var{file-name} @var{file}]
Return a udev file named @var{file-name} containing the rules defined
@@ -12857,10 +12931,10 @@ The following example shows how to use the @var{android-udev-rules}
package so that the Android tool @command{adb} can detect devices
without root privileges. It also details how to create the
@code{adbusers} group, which is required for the proper functioning of
-the rules defined within the @var{android-udev-rules} package. To
+the rules defined within the @code{android-udev-rules} package. To
create such a group, we must define it both as part of the
-@var{supplementary-groups} of our @var{user-account} declaration, as
-well as in the @var{groups} field of the @var{operating-system} record.
+@code{supplementary-groups} of our @code{user-account} declaration, as
+well as in the @var{groups} of the @code{udev-rules-service} procedure.
@lisp
(use-modules (gnu packages android) ;for android-udev-rules
@@ -12874,23 +12948,15 @@ well as in the @var{groups} field of the @var{operating-system} record.
(supplementary-groups
'("adbusers" ;for adb
"wheel" "netdev" "audio" "video")))))
-
- (groups (cons (user-group (system? #t) (name "adbusers"))
- %base-groups))
-
;; @dots{}
-
(services
- (modify-services %desktop-services
- (udev-service-type
- config =>
- (udev-configuration (inherit config)
- (rules (cons android-udev-rules
- (udev-configuration-rules config))))))))
+ (cons (udev-rules-service 'android android-udev-rules
+ #:groups '("adbusers"))
+ %desktop-services)))
@end lisp
@defvr {Scheme Variable} urandom-seed-service-type
-Save some entropy in @var{%random-seed-file} to seed @file{/dev/urandom}
+Save some entropy in @code{%random-seed-file} to seed @file{/dev/urandom}
when rebooting. It also tries to seed @file{/dev/urandom} from
@file{/dev/hwrng} while booting, if @file{/dev/hwrng} exists and is
readable.
@@ -13178,17 +13244,27 @@ their contents in separate files, possibly compressed. The @code{(gnu
services admin)} module provides an interface to GNU@tie{}Rot[t]log, a
log rotation tool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}).
-The example below defines an operating system that provides log rotation
-with the default settings, for commonly encountered log files.
+This service is part of @code{%base-services}, and thus enabled by
+default, with the default settings, for commonly encountered log files.
+The example below shows how to extend it with an additional
+@dfn{rotation}, should you need to do that (usually, services that
+produce log files already take care of that):
@lisp
(use-modules (guix) (gnu))
-(use-service-modules admin mcron)
-(use-package-modules base idutils)
+(use-service-modules admin)
+
+(define my-log-files
+ ;; Log files that I want to rotate.
+ '("/var/log/something.log" "/var/log/another.log"))
(operating-system
;; @dots{}
- (services (cons (service rottlog-service-type)
+ (services (cons (simple-service 'rotate-my-stuff
+ rottlog-service-type
+ (list (log-rotation
+ (frequency 'daily)
+ (files my-log-files))))
%base-services)))
@end lisp
@@ -13259,7 +13335,7 @@ Either @code{#f} or a gexp to execute once the rotation has completed.
@end deftp
@defvr {Scheme Variable} %default-rotations
-Specifies weekly rotation of @var{%rotated-files} and of
+Specifies weekly rotation of @code{%rotated-files} and of
@file{/var/log/guix-daemon.log}.
@end defvr
@@ -13562,6 +13638,68 @@ List of additional command-line arguments to pass to the daemon.
@end table
@end deftp
+@cindex hostapd service, for Wi-Fi access points
+@cindex Wi-Fi access points, hostapd service
+@defvr {Scheme Variable} hostapd-service-type
+This is the service type to run the @uref{https://w1.fi/hostapd/,
+hostapd} daemon to set up WiFi (IEEE 802.11) access points and
+authentication servers. Its associated value must be a
+@code{hostapd-configuration} as shown below:
+
+@lisp
+;; Use wlan1 to run the access point for "My Network".
+(service hostapd-service-type
+ (hostapd-configuration
+ (interface "wlan1")
+ (ssid "My Network")
+ (channel 12)))
+@end lisp
+@end defvr
+
+@deftp {Data Type} hostapd-configuration
+This data type represents the configuration of the hostapd service, with
+the following fields:
+
+@table @asis
+@item @code{package} (default: @code{hostapd})
+The hostapd package to use.
+
+@item @code{interface} (default: @code{"wlan0"})
+The network interface to run the WiFi access point.
+
+@item @code{ssid}
+The SSID (@dfn{service set identifier}), a string that identifies this
+network.
+
+@item @code{broadcast-ssid?} (default: @code{#t})
+Whether to broadcast this SSID.
+
+@item @code{channel} (default: @code{1})
+The WiFi channel to use.
+
+@item @code{driver} (default: @code{"nl80211"})
+The driver interface type. @code{"nl80211"} is used with all Linux
+mac80211 drivers. Use @code{"none"} if building hostapd as a standalone
+RADIUS server that does # not control any wireless/wired driver.
+
+@item @code{extra-settings} (default: @code{""})
+Extra settings to append as-is to the hostapd configuration file. See
+@uref{https://w1.fi/cgit/hostap/plain/hostapd/hostapd.conf} for the
+configuration file reference.
+@end table
+@end deftp
+
+@defvr {Scheme Variable} simulated-wifi-service-type
+This is the type of a service to simulate WiFi networking, which can be
+useful in virtual machines for testing purposes. The service loads the
+Linux kernel
+@uref{https://www.kernel.org/doc/html/latest/networking/mac80211_hwsim/mac80211_hwsim.html,
+@code{mac80211_hwsim} module} and starts hostapd to create a pseudo WiFi
+network that can be seen on @code{wlan0}, by default.
+
+The service's value is a @code{hostapd-configuration} record.
+@end defvr
+
@cindex iptables
@defvr {Scheme Variable} iptables-service-type
This is the service type to set up an iptables configuration. iptables is a
@@ -13719,7 +13857,7 @@ clock synchronized with that of the given servers.
@defvr {Scheme Variable} %openntpd-servers
This variable is a list of the server addresses defined in
-@var{%ntp-servers}.
+@code{%ntp-servers}.
@end defvr
@deftp {Data Type} openntpd-configuration
@@ -13737,7 +13875,7 @@ See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} for more
information.
@item @code{server} (default: @code{'()})
Specify a list of IP addresses or hostnames of NTP servers to synchronize to.
-@item @code{servers} (default: @var{%openntp-servers})
+@item @code{servers} (default: @code{%openntp-servers})
Specify a list of IP addresses or hostnames of NTP pools to synchronize to.
@item @code{constraint-from} (default: @code{'()})
@code{ntpd} can be configured to query the ‘Date’ from trusted HTTPS servers via TLS.
@@ -14553,15 +14691,15 @@ The default SLiM theme and its name.
@deftp {Data Type} sddm-configuration
-This is the data type representing the sddm service configuration.
+This is the data type representing the SDDM service configuration.
@table @asis
@item @code{display-server} (default: "x11")
-Select display server to use for the greeter. Valid values are "x11"
-or "wayland".
+Select display server to use for the greeter. Valid values are
+@samp{"x11"} or @samp{"wayland"}.
@item @code{numlock} (default: "on")
-Valid values are "on", "off" or "none".
+Valid values are @samp{"on"}, @samp{"off"} or @samp{"none"}.
@item @code{halt-command} (default @code{#~(string-apppend #$shepherd "/sbin/halt")})
Command to run when halting.
@@ -14570,7 +14708,8 @@ Command to run when halting.
Command to run when rebooting.
@item @code{theme} (default "maldives")
-Theme to use. Default themes provided by SDDM are "elarun", "maldives" or "maya".
+Theme to use. Default themes provided by SDDM are @samp{"elarun"},
+@samp{"maldives"} or @samp{"maya"}.
@item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes")
Directory to look for themes.
@@ -15058,9 +15197,9 @@ Defaults to @samp{#f}.
@deftypevr {@code{cups-configuration} parameter} string classification
Specifies the security classification of the server. Any valid banner
-name can be used, including "classified", "confidential", "secret",
-"topsecret", and "unclassified", or the banner can be omitted to disable
-secure printing functions.
+name can be used, including @samp{"classified"}, @samp{"confidential"},
+@samp{"secret"}, @samp{"topsecret"}, and @samp{"unclassified"}, or the
+banner can be omitted to disable secure printing functions.
Defaults to @samp{""}.
@end deftypevr
@@ -15262,7 +15401,7 @@ Defaults to @samp{()}.
@deftypevr {@code{method-access-controls} parameter} access-control-list access-controls
Access control directives, as a list of strings. Each string should be
-one directive, such as "Order allow,deny".
+one directive, such as @samp{"Order allow,deny"}.
Defaults to @samp{()}.
@end deftypevr
@@ -15343,7 +15482,7 @@ Defaults to @samp{0}.
@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-job-time
Specifies the maximum time a job may take to print before it is
-canceled, in seconds. Set to 0 to disable cancellation of "stuck" jobs.
+canceled, in seconds. Set to 0 to disable cancellation of ``stuck'' jobs.
Defaults to @samp{10800}.
@end deftypevr
@@ -16151,6 +16290,13 @@ sound server. It exists to allow system overrides of the default settings
via @code{pulseaudio-configuration}, see below.
@quotation Warning
+This service overrides per-user configuration files. If you want
+PulseAudio to honor configuraton files in @file{~/.config/pulse} you
+have to unset the environment variables @code{PULSE_CONFIG} and
+@code{PULSE_CLIENTCONFIG} in your @file{~/.bash_profile}.
+@end quotation
+
+@quotation Warning
This service on its own does not ensure, that the @code{pulseaudio} package
exists on your machine. It merely adds configuration files for it, as
detailed below. In the (admittedly unlikely) case, that you find yourself
@@ -17078,12 +17224,12 @@ if the user doesn't yet have any mail, so you should explicitly tell
Dovecot the full location.
If you're using mbox, giving a path to the INBOX
-file (e.g.@: /var/mail/%u) isn't enough. You'll also need to tell Dovecot
-where the other mailboxes are kept. This is called the "root mail
-directory", and it must be the first path given in the
+file (e.g.@: @file{/var/mail/%u}) isn't enough. You'll also need to tell Dovecot
+where the other mailboxes are kept. This is called the @emph{root mail
+directory}, and it must be the first path given in the
@samp{mail-location} setting.
-There are a few special variables you can use, eg.:
+There are a few special variables you can use, e.g.:
@table @samp
@item %u
@@ -17120,31 +17266,31 @@ Defaults to @samp{""}.
@deftypevr {@code{dovecot-configuration} parameter} string mail-privileged-group
Group to enable temporarily for privileged operations. Currently
this is used only with INBOX when either its initial creation or
-dotlocking fails. Typically this is set to "mail" to give access to
-/var/mail.
+dotlocking fails. Typically this is set to @samp{"mail"} to give access to
+@file{/var/mail}.
Defaults to @samp{""}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string mail-access-groups
Grant access to these supplementary groups for mail processes.
Typically these are used to set up access to shared mailboxes. Note
-that it may be dangerous to set these if users can create
-symlinks (e.g.@: if "mail" group is set here, ln -s /var/mail ~/mail/var
-could allow a user to delete others' mailboxes, or ln -s
-/secret/shared/box ~/mail/mybox would allow reading it).
-Defaults to @samp{""}.
+that it may be dangerous to set these if users can create symlinks
+(e.g.@: if @samp{mail} group is set here, @code{ln -s /var/mail ~/mail/var}
+could allow a user to delete others' mailboxes, or @code{ln -s
+/secret/shared/box ~/mail/mybox} would allow reading it). Defaults to
+@samp{""}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access?
Allow full file system access to clients. There's no access checks
other than what the operating system does for the active UID/GID. It
works with both maildir and mboxes, allowing you to prefix mailboxes
-names with e.g.@: /path/ or ~user/.
+names with e.g.@: @file{/path/} or @file{~user/}.
Defaults to @samp{#f}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable?
-Don't use mmap() at all. This is required if you store indexes to
+Don't use @code{mmap()} at all. This is required if you store indexes to
shared file systems (NFS or clustered file system).
Defaults to @samp{#f}.
@end deftypevr
@@ -17162,7 +17308,7 @@ When to use fsync() or fdatasync() calls:
@item optimized
Whenever necessary to avoid losing important data
@item always
-Useful with e.g.@: NFS when write()s are delayed
+Useful with e.g.@: NFS when @code{write()}s are delayed
@item never
Never use it (best performance, but crashes can lose data).
@end table
@@ -17229,10 +17375,10 @@ Defaults to @samp{50}.
@deftypevr {@code{dovecot-configuration} parameter} colon-separated-file-name-list valid-chroot-dirs
List of directories under which chrooting is allowed for mail
-processes (i.e.@: /var/mail will allow chrooting to /var/mail/foo/bar
+processes (i.e.@: @file{/var/mail} will allow chrooting to @file{/var/mail/foo/bar}
too). This setting doesn't affect @samp{login-chroot}
@samp{mail-chroot} or auth chroot settings. If this setting is empty,
-"/./" in home dirs are ignored. WARNING: Never add directories here
+@samp{/./} in home dirs are ignored. WARNING: Never add directories here
which local users can modify, that may lead to root exploit. Usually
this should be done only if you don't allow shell access for users.
<doc/wiki/Chrooting.txt>.
@@ -17241,11 +17387,11 @@ Defaults to @samp{()}.
@deftypevr {@code{dovecot-configuration} parameter} string mail-chroot
Default chroot directory for mail processes. This can be overridden
-for specific users in user database by giving /./ in user's home
-directory (e.g.@: /home/./user chroots into /home). Note that usually
+for specific users in user database by giving @samp{/./} in user's home
+directory (e.g.@: @samp{/home/./user} chroots into @file{/home}). Note that usually
there is no real need to do chrooting, Dovecot doesn't allow users to
access files outside their mail directory anyway. If your home
-directories are prefixed with the chroot directory, append "/."@: to
+directories are prefixed with the chroot directory, append @samp{/.} to
@samp{mail-chroot}. <doc/wiki/Chrooting.txt>.
Defaults to @samp{""}.
@end deftypevr
@@ -18352,7 +18498,7 @@ Curve for Elliptic curve Diffie-Hellman. Prosody's default is
@end deftypevr
@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verifyext
-A list of "extra" verification options.
+A list of ``extra'' verification options.
@end deftypevr
@deftypevr {@code{ssl-configuration} parameter} maybe-string password
@@ -18440,7 +18586,7 @@ example if you want your users to have addresses like
@samp{"john.smith@@example.com"} then you need to add a host
@samp{"example.com"}. All options in this list will apply only to this host.
-Note: the name "virtual" host is used in configuration to avoid confusion with
+Note: the name @emph{virtual} host is used in configuration to avoid confusion with
the actual physical host that Prosody is installed on. A single Prosody
instance can serve many domains, each one defined as a VirtualHost entry in
Prosody's configuration. Conversely a server that hosts a single domain would
@@ -18486,7 +18632,7 @@ Multi-user chat (MUC) is Prosody's module for allowing you to create
hosted chatrooms/conferences for XMPP users.
General information on setting up and using multi-user chatrooms can be found
-in the "Chatrooms" documentation (@url{https://prosody.im/doc/chatrooms}),
+in the ``Chatrooms'' documentation (@url{https://prosody.im/doc/chatrooms}),
which you should read if you are new to XMPP chatrooms.
See also @url{https://prosody.im/doc/modules/mod_muc}.
@@ -19561,11 +19707,12 @@ Defaults to @samp{"nslcd"}.
@deftypevr {@code{nslcd-configuration} parameter} log-option log
This option controls the way logging is done via a list containing
-SCHEME and LEVEL. The SCHEME argument may either be the symbols "none"
-or "syslog", or an absolute file name. The LEVEL argument is optional
-and specifies the log level. The log level may be one of the following
-symbols: "crit", "error", "warning", "notice", "info" or "debug". All
-messages with the specified log level or higher are logged.
+SCHEME and LEVEL. The SCHEME argument may either be the symbols
+@samp{none} or @samp{syslog}, or an absolute file name. The LEVEL
+argument is optional and specifies the log level. The log level may be
+one of the following symbols: @samp{crit}, @samp{error}, @samp{warning},
+@samp{notice}, @samp{info} or @samp{debug}. All messages with the
+specified log level or higher are logged.
Defaults to @samp{("/var/log/nslcd" info)}.
@@ -20682,6 +20829,30 @@ but it also fetches and indexes mail retrieved from Debbugs.
This is the service type for Mumi.
@end defvr
+@deftp {Data Type} mumi-configuration
+Data type representing the Mumi service configuration. This type has the
+following fields:
+
+@table @asis
+@item @code{mumi} (default: @code{mumi})
+The Mumi package to use.
+
+@item @code{mailer?} (default: @code{#true})
+Whether to enable or disable the mailer component.
+
+@item @code{mumi-configuration-sender}
+The email address used as the sender for comments.
+
+@item @code{mumi-configuration-smtp}
+A URI to configure the SMTP settings for Mailutils. This could be
+something like @code{sendmail:///path/to/bin/msmtp} or any other URI
+supported by Mailutils. @xref{SMTP Mailboxes, SMTP Mailboxes,,
+mailutils, GNU@tie{}Mailutils}.
+
+@end table
+@end deftp
+
+
@subsubheading FastCGI
@cindex fastcgi
@cindex fcgiwrap
@@ -20850,7 +21021,7 @@ The time in seconds after which a process with no requests is killed.
@end deftp
-@deffn {Scheme Procedure} nginx-php-fpm-location @
+@deffn {Scheme Procedure} nginx-php-location @
[#:nginx-package nginx] @
[socket (string-append "/var/run/php" @
(version-major (package-version php)) @
@@ -23423,7 +23594,7 @@ Defaults to @samp{()}.
@deftypevr {@code{libvirt-configuration} parameter} string tls-priority
Override the compile time default TLS priority string. The default is
-usually "NORMAL" unless overridden at build time. Only set this is it
+usually @samp{"NORMAL"} unless overridden at build time. Only set this is it
is desired for libvirt to deviate from the global default settings.
Defaults to @samp{"NORMAL"}.
@@ -23557,11 +23728,12 @@ x:+name
where @code{name} is a string which is matched against the category
given in the @code{VIR_LOG_INIT()} at the top of each libvirt source
-file, e.g., "remote", "qemu", or "util.json" (the name in the filter can
-be a substring of the full category name, in order to match multiple
-similar categories), the optional "+" prefix tells libvirt to log stack
-trace for each message matching name, and @code{x} is the minimal level
-where matching messages should be logged:
+file, e.g., @samp{"remote"}, @samp{"qemu"}, or @samp{"util.json"} (the
+name in the filter can be a substring of the full category name, in
+order to match multiple similar categories), the optional @samp{"+"}
+prefix tells libvirt to log stack trace for each message matching name,
+and @code{x} is the minimal level where matching messages should be
+logged:
@itemize @bullet
@item
@@ -23979,7 +24151,7 @@ expose repositories over the Git protocol for anonymous access.
The optional @var{config} argument should be a
@code{<git-daemon-configuration>} object, by default it allows read-only
access to exported@footnote{By creating the magic file
-"git-daemon-export-ok" in the repository directory.} repositories under
+@file{git-daemon-export-ok} in the repository directory.} repositories under
@file{/srv/git}.
@end deffn
@@ -24646,7 +24818,7 @@ Defaults to @samp{"a fast webinterface for the git dscm"}.
@deftypevr {@code{cgit-configuration} parameter} string root-readme
The content of the file specified with this option will be included
-verbatim below the "about" link on the repository index page.
+verbatim below the ``about'' link on the repository index page.
Defaults to @samp{""}.
@@ -24663,8 +24835,8 @@ Defaults to @samp{""}.
If set to @samp{#t} and repository-directory is enabled,
repository-directory will recurse into directories whose name starts
with a period. Otherwise, repository-directory will stay away from such
-directories, considered as "hidden". Note that this does not apply to
-the ".git" directory in non-bare repos.
+directories, considered as ``hidden''. Note that this does not apply to
+the @file{.git} directory in non-bare repos.
Defaults to @samp{#f}.
@@ -24727,7 +24899,7 @@ Defaults to @samp{""}.
@end deftypevr
@deftypevr {@code{cgit-configuration} parameter} integer summary-branches
-Specifies the number of branches to display in the repository "summary"
+Specifies the number of branches to display in the repository ``summary''
view.
Defaults to @samp{10}.
@@ -24736,14 +24908,14 @@ Defaults to @samp{10}.
@deftypevr {@code{cgit-configuration} parameter} integer summary-log
Specifies the number of log entries to display in the repository
-"summary" view.
+``summary'' view.
Defaults to @samp{10}.
@end deftypevr
@deftypevr {@code{cgit-configuration} parameter} integer summary-tags
-Specifies the number of tags to display in the repository "summary"
+Specifies the number of tags to display in the repository ``summary''
view.
Defaults to @samp{10}.
@@ -24835,7 +25007,7 @@ Defaults to @samp{""}.
@deftypevr {@code{repository-cgit-configuration} parameter} repo-string defbranch
The name of the default branch for this repository. If no such branch
exists in the repository, the first branch name (when sorted) is used as
-default instead. By default branch pointed to by HEAD, or "master" if
+default instead. By default branch pointed to by HEAD, or ``master'' if
there is no suitable HEAD.
Defaults to @samp{""}.
@@ -24996,7 +25168,7 @@ Defaults to @samp{""}.
@deftypevr {@code{repository-cgit-configuration} parameter} repo-string readme
A path (relative to repo) which specifies a file to include verbatim as
-the "About" page for this repo.
+the ``About'' page for this repo.
Defaults to @samp{""}.
@@ -25135,7 +25307,7 @@ A value like @code{#o0027} will give read access to the group used by Gitolite
like cgit or gitweb.
@item @code{git-config-keys} (default: @code{""})
-Gitolite allows you to set git config values using the "config" keyword. This
+Gitolite allows you to set git config values using the @samp{config} keyword. This
setting allows control over the config keys to accept.
@item @code{roles} (default: @code{'(("READERS" . 1) ("WRITERS" . ))})
@@ -25383,6 +25555,42 @@ notifications.
@end table
@end deftp
+@cindex modprobe
+@cindex kernel module loader
+@subsubsection Kernel Module Loader Service
+
+The kernel module loader service allows one to load loadable kernel
+modules at boot. This is especially useful for modules that don't
+autoload and need to be manually loaded, as it's the case with
+@code{ddcci}.
+
+@deffn {Scheme Variable} kernel-module-loader-service-type
+The service type for loading loadable kernel modules at boot with
+@command{modprobe}. Its value must be a list of strings representing
+module names. For example loading the drivers provided by
+@code{ddcci-driver-linux}, in debugging mode by passing some module
+parameters, can be done as follow:
+
+@lisp
+(use-modules (gnu) (gnu services))
+(use-package-modules linux)
+(use-service-modules linux)
+
+(define ddcci-config
+ (plain-file "ddcci.conf"
+ "options ddcci dyndbg delay=120"))
+
+(operating-system
+ ...
+ (services (cons* (service kernel-module-loader-service-type
+ '("ddcci" "ddcci_backlight"))
+ (simple-service 'ddcci-config etc-service-type
+ (list `("modprobe.d/ddcci.conf"
+ ,ddcci-config)))
+ %base-services))
+ (kernel-loadable-modules (list ddcci-driver-linux)))
+@end lisp
+@end deffn
@node Miscellaneous Services
@subsection Miscellaneous Services
@@ -25529,6 +25737,11 @@ If true, this must be the name of a file to log messages to.
@cindex dictionary
The @code{(gnu services dict)} module provides the following service:
+@defvr {Scheme Variable} dicod-service-type
+This is the type of the service that runs the @command{dicod} daemon, an
+implementation of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
+@end defvr
+
@deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)]
Return a service that runs the @command{dicod} daemon, an implementation
of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
@@ -26981,8 +27194,8 @@ evaluates to. As an example, @var{file} might contain a definition like this:
The file should evaluate to a list of @var{machine} objects. This example,
upon being deployed, will create a new generation on the remote system
-realizing the @code{operating-system} declaration @var{%system}.
-@var{environment} and @var{configuration} specify how the machine should be
+realizing the @code{operating-system} declaration @code{%system}.
+@code{environment} and @code{configuration} specify how the machine should be
provisioned---that is, how the computing resources should be created and
managed. The above example does not create any resources, as a
@code{'managed-host} is a machine that is already running the Guix system and
@@ -27124,7 +27337,8 @@ This image boots the Xfce graphical environment and it contains some
commonly-used tools. You can install more software in the image by running
@command{guix package} in a terminal (@pxref{Invoking guix package}). You can
also reconfigure the system based on its initial configuration file available
-as @file{/etc/config.scm} (@pxref{Using the Configuration System}).
+as @file{/run/current-system/configuration.scm} (@pxref{Using the
+Configuration System}).
Instead of using this pre-built image, one can also build their own virtual
machine image using @command{guix system vm-image} (@pxref{Invoking guix
@@ -27235,7 +27449,8 @@ VM. To enable that you'll also have to pass the following flags to @command{qem
name=com.redhat.spice.0
@end example
-You'll also need to add the @pxref{Miscellaneous Services, Spice service}.
+You'll also need to add the @code{(spice-vdagent-service)} to your
+system definition (@pxref{Miscellaneous Services, Spice service}).
@node Defining Services
@section Defining Services
diff --git a/doc/local.mk b/doc/local.mk
index 3805593172..f8709bb3a4 100644
--- a/doc/local.mk
+++ b/doc/local.mk
@@ -1,6 +1,6 @@
# GNU Guix --- Functional package management for GNU
# Copyright © 2016 Eric Bavier <bavier@member.fsf.org>
-# Copyright © 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Ludovic Courtès <ludo@gnu.org>
+# Copyright © 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 Ludovic Courtès <ludo@gnu.org>
# Copyright © 2013 Andreas Enge <andreas@enge.fr>
# Copyright © 2016 Taylan Ulrich Bayırlı/Kammer <taylanbayirli@gmail.com>
# Copyright © 2016, 2018 Mathieu Lirzin <mthl@gnu.org>
@@ -53,7 +53,8 @@ EXTRA_DIST += \
$(DOT_VECTOR_GRAPHICS) \
%D%/images/coreutils-size-map.eps \
%D%/environment-gdb.scm \
- %D%/package-hello.scm
+ %D%/package-hello.scm \
+ %D%/package-hello.json
OS_CONFIG_EXAMPLES_TEXI = \
%D%/os-config-bare-bones.texi \
@@ -184,6 +185,7 @@ sub_commands_mans = \
$(srcdir)/%D%/guix-archive.1 \
$(srcdir)/%D%/guix-build.1 \
$(srcdir)/%D%/guix-challenge.1 \
+ $(srcdir)/%D%/guix-deploy.1 \
$(srcdir)/%D%/guix-download.1 \
$(srcdir)/%D%/guix-edit.1 \
$(srcdir)/%D%/guix-environment.1 \
@@ -196,12 +198,19 @@ sub_commands_mans = \
$(srcdir)/%D%/guix-pull.1 \
$(srcdir)/%D%/guix-refresh.1 \
$(srcdir)/%D%/guix-size.1 \
- $(srcdir)/%D%/guix-system.1
+ $(srcdir)/%D%/guix-system.1 \
+ $(srcdir)/%D%/guix-time-machine.1 \
+ $(srcdir)/%D%/guix-weather.1
+
+# Assume that cross-compiled commands cannot be executed.
+if !CROSS_COMPILING
dist_man1_MANS = \
$(srcdir)/%D%/guix.1 \
$(sub_commands_mans)
+endif
+
gen_man = \
LANGUAGE= $(top_builddir)/pre-inst-env $(HELP2MAN) \
$(HELP2MANFLAGS)
@@ -223,10 +232,12 @@ $(srcdir)/%D%/guix-%.1: guix/scripts/%.scm $(GOBJECTS)
esac
if BUILD_DAEMON
+if !CROSS_COMPILING
dist_man1_MANS += $(srcdir)/%D%/guix-daemon.1
-$(srcdir)/%D%/guix-daemon.1: nix/nix-daemon/guix-daemon.cc
+$(srcdir)/%D%/guix-daemon.1: guix-daemon$(EXEEXT)
-$(AM_V_HELP2MAN)$(gen_man) --output="$@" `basename "$@" .1`
endif
+endif
diff --git a/doc/package-hello.json b/doc/package-hello.json
new file mode 100644
index 0000000000..a47e266e4b
--- /dev/null
+++ b/doc/package-hello.json
@@ -0,0 +1,31 @@
+[
+ {
+ "name": "myhello",
+ "version": "2.10",
+ "source": "mirror://gnu/hello/hello-2.10.tar.gz",
+ "build-system": "gnu",
+ "arguments": {
+ "tests?": false
+ }
+ "home-page": "https://www.gnu.org/software/hello/",
+ "synopsis": "Hello, GNU world: An example GNU package",
+ "description": "GNU Hello prints a greeting.",
+ "license": "GPL-3.0+",
+ "native-inputs": ["gettext"]
+ },
+ {
+ "name": "greeter",
+ "version": "1.0",
+ "source": "https://example.com/greeter-1.0.tar.gz",
+ "build-system": "gnu",
+ "arguments": {
+ "test-target": "foo",
+ "parallel-build?": false,
+ },
+ "home-page": "https://example.com/",
+ "synopsis": "Greeter using GNU Hello",
+ "description": "This is a wrapper around GNU Hello.",
+ "license": "GPL-3.0+",
+ "inputs": ["myhello", "hello"]
+ }
+]
generated by cgit v1.2.3 (git 2.49.0) at 2025-05-08 11:13:03 +0000