[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
02/02: doc: Use @lisp instead of @example for Scheme snippets.
|
From: |
guix-commits |
|
Subject: |
02/02: doc: Use @lisp instead of @example for Scheme snippets. |
|
Date: |
Sat, 7 Sep 2019 12:42:17 -0400 (EDT) |
civodul pushed a commit to branch master
in repository guix.
commit 8ba31e8bd1f780301a429bbd826aa26daad9e71c
Author: Ludovic Courtès <address@hidden>
Date: Sat Sep 7 18:21:01 2019 +0200
doc: Use @lisp instead of @example for Scheme snippets.
This is a followup to f8c143a7131d6f40f387f4cd2ad1fa78b5e2f429, which
allows syntax highlighting of @lisp snippets in the HTML output.
* doc/guix.texi, doc/contributing.texi: Use @lisp instead of @example
for all the Scheme snippets.
---
doc/contributing.texi | 16 +-
doc/guix.texi | 642 +++++++++++++++++++++++++-------------------------
2 files changed, 329 insertions(+), 329 deletions(-)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index 5991719..655c828 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -376,7 +376,7 @@ package and does not contain any version number.
For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as
follows:
-@example
+@lisp
(define-public gtk+
(package
(name "gtk+")
@@ -387,15 +387,15 @@ For instance, the versions 2.24.20 and 3.9.12 of GTK+ may
be packaged as follows
(name "gtk+")
(version "2.24.20")
...))
-@end example
+@end lisp
If we also wanted GTK+ 3.8.2, this would be packaged as
-@example
+@lisp
(define-public gtk+-3.8
(package
(name "gtk+")
(version "3.8.2")
...))
-@end example
+@end lisp
@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
@c for a discussion of what follows.
@@ -432,7 +432,7 @@ kernel.) It is best to use the full commit identifiers in
@code{origin}s, though, to avoid ambiguities. A typical package
definition may look like this:
-@example
+@lisp
(define my-package
(let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
(revision "1")) ;Guix package revision
@@ -447,7 +447,7 @@ definition may look like this:
(file-name (git-file-name name version))))
;; @dots{}
)))
-@end example
+@end lisp
@node Synopses and Descriptions
@subsection Synopses and Descriptions
@@ -825,12 +825,12 @@ recommend using the @code{qemu-binfmt-service-type} to
emulate them. In
order to enable it, add the following service to the list of services in
your @code{operating-system} configuration:
-@example
+@lisp
(service qemu-binfmt-service-type
(qemu-binfmt-configuration
(platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el"))
(guix-support? #t)))
-@end example
+@end lisp
Then reconfigure your system.
diff --git a/doc/guix.texi b/doc/guix.texi
index 6d6a09b..83f791d 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -1035,7 +1035,7 @@ build are copied back to the initial machine.
The @file{/etc/guix/machines.scm} file typically looks like this:
-@example
+@lisp
(list (build-machine
(name "eightysix.example.org")
(system "x86_64-linux")
@@ -1051,7 +1051,7 @@ The @file{/etc/guix/machines.scm} file typically looks
like this:
(private-key
(string-append (getenv "HOME")
"/.ssh/identity-for-guix"))))
-@end example
+@end lisp
@noindent
In the example above we specify a list of two build machines, one for
@@ -2756,9 +2756,9 @@ Install the package that the code within @var{file}
evaluates to.
As an example, @var{file} might contain a definition like this
(@pxref{Defining Packages}):
-@example
+@lisp
@verbatiminclude package-hello.scm
-@end example
+@end lisp
Developers may find it useful to include such a @file{guix.scm} file
in the root of their project source tree that can be used to test
@@ -2814,7 +2814,7 @@ so on.
of packages:
@findex packages->manifest
-@example
+@lisp
(use-package-modules guile emacs)
(packages->manifest
@@ -2822,7 +2822,7 @@ of packages:
guile-2.0
;; Use a specific package output.
(list guile-2.0 "debug")))
-@end example
+@end lisp
@findex specifications->manifest
In this example we have to know which modules define the @code{emacs}
@@ -2832,10 +2832,10 @@ instead provide regular package specifications and let
@code{specifications->manifest} look up the corresponding package
objects, like this:
-@example
+@lisp
(specifications->manifest
'("emacs" "guile@@2.2" "guile@@2.2:debug"))
-@end example
+@end lisp
@item --roll-back
@cindex rolling back
@@ -4548,9 +4548,9 @@ within @var{file} evaluates to.
As an example, @var{file} might contain a definition like this
(@pxref{Defining Packages}):
-@example
+@lisp
@verbatiminclude environment-gdb.scm
-@end example
+@end lisp
@item --manifest=@var{file}
@itemx -m @var{file}
@@ -5124,7 +5124,7 @@ The high-level interface to package definitions is
implemented in the
example, the package definition, or @dfn{recipe}, for the GNU Hello
package looks like this:
-@example
+@lisp
(define-module (gnu packages hello)
#:use-module (guix packages)
#:use-module (guix download)
@@ -5150,7 +5150,7 @@ package looks like this:
(description "Guess what GNU Hello prints!")
(home-page "https://www.gnu.org/software/hello/";)
(license gpl3+)))
-@end example
+@end lisp
@noindent
Without being a Scheme expert, the reader may have guessed the meaning
@@ -5331,7 +5331,7 @@ the name of a package and returns its new name after
rewrite.
@noindent
Consider this example:
-@example
+@lisp
(define libressl-instead-of-openssl
;; This is a procedure to replace OPENSSL by LIBRESSL,
;; recursively.
@@ -5339,7 +5339,7 @@ Consider this example:
(define git-with-libressl
(libressl-instead-of-openssl git))
-@end example
+@end lisp
@noindent
Here we first define a rewriting procedure that replaces @var{openssl}
@@ -5361,11 +5361,11 @@ replacement for that package.
The example above could be rewritten this way:
-@example
+@lisp
(define libressl-instead-of-openssl
;; Replace all the packages called "openssl" with LibreSSL.
(package-input-rewriting/spec `(("openssl" . ,(const libressl)))))
-@end example
+@end lisp
The key difference here is that, this time, packages are matched by spec and
not by identity. In other words, any package in the graph that is called
@@ -5431,11 +5431,11 @@ defaults to @code{"out"} (@pxref{Packages with Multiple
Outputs}, for
more on package outputs). For example, the list below specifies three
inputs:
-@example
+@lisp
`(("libffi" ,libffi)
("libunistring" ,libunistring)
("glib:bin" ,glib "bin")) ;the "bin" output of Glib
-@end example
+@end lisp
@cindex cross compilation, package dependencies
The distinction between @code{native-inputs} and @code{inputs} is
@@ -5516,7 +5516,7 @@ identifier resolves to the package being defined.
The example below shows how to add a package as a native input of itself when
cross-compiling:
-@example
+@lisp
(package
(name "guile")
;; ...
@@ -5526,7 +5526,7 @@ cross-compiling:
(native-inputs (if (%current-target-system)
`(("self" ,this-package))
'())))
-@end example
+@end lisp
It is an error to refer to @code{this-package} outside a package definition.
@end deffn
@@ -5563,11 +5563,11 @@ clone the Git version control repository, and check out
the revision
specified in the @code{uri} field as a @code{git-reference} object; a
@code{git-reference} looks like this:
-@example
+@lisp
(git-reference
(url "https://git.savannah.gnu.org/git/hello.git";)
(commit "v2.10"))
-@end example
+@end lisp
@end table
@item @code{sha256}
@@ -6779,7 +6779,7 @@ in a monad---values that carry this additional
context---are called
Consider this ``normal'' procedure:
-@example
+@lisp
(define (sh-symlink store)
;; Return a derivation that symlinks the 'bash' executable.
(let* ((drv (package-derivation store bash))
@@ -6787,19 +6787,19 @@ Consider this ``normal'' procedure:
(sh (string-append out "/bin/bash")))
(build-expression->derivation store "sh"
`(symlink ,sh %output))))
-@end example
+@end lisp
Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten
as a monadic function:
-@example
+@lisp
(define (sh-symlink)
;; Same, but return a monadic value.
(mlet %store-monad ((drv (package->derivation bash)))
(gexp->derivation "sh"
#~(symlink (string-append #$drv "/bin/bash")
#$output))))
-@end example
+@end lisp
There are several things to note in the second version: the @code{store}
parameter is now implicit and is ``threaded'' in the calls to the
@@ -6811,12 +6811,12 @@ As it turns out, the call to @code{package->derivation}
can even be
omitted since it will take place implicitly, as we will see later
(@pxref{G-Expressions}):
-@example
+@lisp
(define (sh-symlink)
(gexp->derivation "sh"
#~(symlink (string-append #$bash "/bin/bash")
#$output)))
-@end example
+@end lisp
@c See
@c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/>
@@ -6826,10 +6826,10 @@ said, ``you exit a monad like you exit a building on
fire: by running''.
So, to exit the monad and get the desired effect, one must use
@code{run-with-store}:
-@example
+@lisp
(run-with-store (open-connection) (sh-symlink))
@result{} /gnu/store/...-sh-symlink
-@end example
+@end lisp
Note that the @code{(guix monad-repl)} module extends the Guile REPL with
new ``meta-commands'' to make it easier to deal with monadic procedures:
@@ -6878,7 +6878,7 @@ Guile. Thus we use this somewhat cryptic symbol
inherited from the
Haskell language.}. There can be one @var{mproc} or several of them, as
in this example:
-@example
+@lisp
(run-with-state
(with-monad %state-monad
(>>= (return 1)
@@ -6888,7 +6888,7 @@ in this example:
@result{} 4
@result{} some-state
-@end example
+@end lisp
@end deffn
@deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
@@ -6947,7 +6947,7 @@ Consider the example below. The @code{square} procedure
returns a value
in the state monad. It returns the square of its argument, but also
increments the current state value:
-@example
+@lisp
(define (square x)
(mlet %state-monad ((count (current-state)))
(mbegin %state-monad
@@ -6957,7 +6957,7 @@ increments the current state value:
(run-with-state (sequence %state-monad (map square (iota 3))) 0)
@result{} (0 1 4)
@result{} 3
-@end example
+@end lisp
When ``run'' through @var{%state-monad}, we obtain that additional state
value, which is the number of @code{square} calls.
@@ -7032,14 +7032,14 @@ entries for which @var{select?} does not return true.
The example below adds a file to the store, under two different names:
-@example
+@lisp
(run-with-store (open-connection)
(mlet %store-monad ((a (interned-file "README"))
(b (interned-file "README" "LEGU-MIN")))
(return (list a b))))
@result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
-@end example
+@end lisp
@end deffn
@@ -7133,22 +7133,22 @@ below.)
To illustrate the idea, here is an example of a gexp:
-@example
+@lisp
(define build-exp
#~(begin
(mkdir #$output)
(chdir #$output)
(symlink (string-append #$coreutils "/bin/ls")
"list-files")))
-@end example
+@end lisp
This gexp can be passed to @code{gexp->derivation}; we obtain a
derivation that builds a directory containing exactly one symlink to
@file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
-@example
+@lisp
(gexp->derivation "the-thing" build-exp)
-@end example
+@end lisp
As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
substituted to the reference to the @var{coreutils} package in the
@@ -7164,7 +7164,7 @@ host---versus references to cross builds of a package.
To that end, the
@code{#+} plays the same role as @code{#$}, but is a reference to a
native package build:
-@example
+@lisp
(gexp->derivation "vi"
#~(begin
(mkdir #$output)
@@ -7173,7 +7173,7 @@ native package build:
(string-append #$emacs "/bin/emacs")
(string-append #$output "/bin/vi")))
#:target "mips64el-linux-gnu")
-@end example
+@end lisp
@noindent
In the example above, the native build of @var{coreutils} is used, so
@@ -7187,7 +7187,7 @@ able to use certain Guile modules from the ``host
environment'' in the
gexp, so those modules should be imported in the ``build environment''.
The @code{with-imported-modules} form allows you to express that:
-@example
+@lisp
(let ((build (with-imported-modules '((guix build utils))
#~(begin
(use-modules (guix build utils))
@@ -7197,7 +7197,7 @@ The @code{with-imported-modules} form allows you to
express that:
#$build
(display "success!\n")
#t)))
-@end example
+@end lisp
@noindent
In this example, the @code{(guix build utils)} module is automatically
@@ -7213,7 +7213,7 @@ because of missing dependent modules. The
@code{source-module-closure}
procedure computes the closure of a module by looking at its source file
headers, which comes in handy in this case:
-@example
+@lisp
(use-modules (guix modules)) ;for 'source-module-closure'
(with-imported-modules (source-module-closure
@@ -7224,7 +7224,7 @@ headers, which comes in handy in this case:
(use-modules (guix build utils)
(gnu build vm))
@dots{})))
-@end example
+@end lisp
@cindex extensions, for gexps
@findex with-extensions
@@ -7233,7 +7233,7 @@ modules, but also ``extensions'' such as Guile bindings
to C libraries
or other ``full-blown'' packages. Say you need the @code{guile-json}
package available on the build side, here's how you would do it:
-@example
+@lisp
(use-modules (gnu packages guile)) ;for 'guile-json'
(with-extensions (list guile-json)
@@ -7241,7 +7241,7 @@ package available on the build side, here's how you would
do it:
#~(begin
(use-modules (json))
@dots{})))
-@end example
+@end lisp
The syntactic form to construct gexps is summarized below.
@@ -7310,12 +7310,12 @@ Each item in @var{modules} can be the name of a module,
such as
@code{(guix build utils)}, or it can be a module name, followed by an
arrow, followed by a file-like object:
-@example
+@lisp
`((guix build utils)
(guix gcrypt)
((guix config) => ,(scheme-file "config.scm"
#~(define-module @dots{}))))
-@end example
+@end lisp
@noindent
In the example above, the first two modules are taken from the search
@@ -7414,10 +7414,10 @@ The @code{local-file}, @code{plain-file},
@code{computed-file},
@dfn{file-like objects}. That is, when unquoted in a G-expression,
these objects lead to a file in the store. Consider this G-expression:
-@example
+@lisp
#~(system* #$(file-append glibc "/sbin/nscd") "-f"
#$(local-file "/tmp/my-nscd.conf"))
-@end example
+@end lisp
The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it
to the store. Once expanded, for instance @i{via}
@@ -7473,13 +7473,13 @@ Look up @var{exp}'s modules in @var{module-path}.
The example below builds a script that simply invokes the @command{ls}
command:
-@example
+@lisp
(use-modules (guix gexp) (gnu packages base))
(gexp->script "list-files"
#~(execl #$(file-append coreutils "/bin/ls")
"ls"))
-@end example
+@end lisp
When ``running'' it through the store (@pxref{The Store Monad,
@code{run-with-store}}), we obtain a derivation that produces an
@@ -7537,14 +7537,14 @@ to create will reference items from the store. This is
typically the
case when building a configuration file that embeds store file names,
like this:
-@example
+@lisp
(define (profile.sh)
;; Return the name of a shell script in the store that
;; initializes the 'PATH' environment variable.
(text-file* "profile.sh"
"export PATH=" coreutils "/bin:"
grep "/bin:" sed "/bin\n"))
-@end example
+@end lisp
In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
will reference @var{coreutils}, @var{grep}, and @var{sed}, thereby
@@ -7556,10 +7556,10 @@ Return an object representing store file @var{name}
containing
@var{text}. @var{text} is a sequence of strings and file-like objects,
as in:
-@example
+@lisp
(mixed-text-file "profile"
"export PATH=" coreutils "/bin:" grep "/bin")
-@end example
+@end lisp
This is the declarative counterpart of @code{text-file*}.
@end deffn
@@ -7570,13 +7570,13 @@ Each item in @var{files} must be a two-element list
where the first element is t
file name to use in the new directory, and the second element is a gexp
denoting the target file. Here's an example:
-@example
+@lisp
(file-union "etc"
`(("hosts" ,(plain-file "hosts"
"127.0.0.1 localhost"))
("bashrc" ,(plain-file "bashrc"
"alias ls='ls --color=auto'"))))
-@end example
+@end lisp
This yields an @code{etc} directory containing these two files.
@end deffn
@@ -7585,9 +7585,9 @@ This yields an @code{etc} directory containing these two
files.
Return a directory that is the union of @var{things}, where @var{things} is a
list of
file-like objects denoting directories. For example:
-@example
+@lisp
(directory-union "guile+emacs" (list guile emacs))
-@end example
+@end lisp
yields a directory that is the union of the @code{guile} and @code{emacs}
packages.
@end deffn
@@ -7599,19 +7599,19 @@ and @var{suffix}, where @var{obj} is a lowerable object
and each
As an example, consider this gexp:
-@example
+@lisp
(gexp->script "run-uname"
#~(system* #$(file-append coreutils
"/bin/uname")))
-@end example
+@end lisp
The same effect could be achieved with:
-@example
+@lisp
(gexp->script "run-uname"
#~(system* (string-append #$coreutils
"/bin/uname")))
-@end example
+@end lisp
There is one difference though: in the @code{file-append} case, the
resulting script contains the absolute file name as a string, whereas in
@@ -8099,9 +8099,9 @@ Build the package, derivation, or other file-like object
that the code within
As an example, @var{file} might contain a package definition like this
(@pxref{Defining Packages}):
-@example
+@lisp
@verbatiminclude package-hello.scm
-@end example
+@end lisp
@item --expression=@var{expr}
@itemx -e @var{expr}
@@ -8974,13 +8974,13 @@ and @command{guix refresh} needs a little help. Most
updaters honor the
@code{upstream-name} property in package definitions, which can be used
to that effect:
-@example
+@lisp
(define-public network-manager
(package
(name "network-manager")
;; @dots{}
(properties '((upstream-name . "NetworkManager")))))
-@end example
+@end lisp
When passed @code{--update}, it modifies distribution source files to
update the version numbers and source tarball hashes of those package
@@ -9323,14 +9323,14 @@ Package developers can specify in package recipes the
name and version of the package when they differ from the name or version
that Guix uses, as in this example:
-@example
+@lisp
(package
(name "grub")
;; @dots{}
;; CPE calls this package "grub2".
(properties '((cpe-name . "grub2")
(cpe-version . "2.3")))
-@end example
+@end lisp
@c See <https://www.openwall.com/lists/oss-security/2017/03/15/3>.
Some entries in the CVE database do not specify which version of a
@@ -9338,7 +9338,7 @@ package they apply to, and would thus ``stick around''
forever. Package
developers who found CVE alerts and verified they can be ignored can
declare them as in this example:
-@example
+@lisp
(package
(name "t1lib")
;; @dots{}
@@ -9347,7 +9347,7 @@ declare them as in this example:
"CVE-2011-1553"
"CVE-2011-1554"
"CVE-2011-5244")))))
-@end example
+@end lisp
@item formatting
Warn about obvious source code formatting issues: trailing white space,
@@ -10447,11 +10447,11 @@ mode, as in the example above. However, more recent
machines rely instead on
the @dfn{Unified Extensible Firmware Interface} (UEFI) to boot. In that case,
the @code{bootloader} field should contain something along these lines:
-@example
+@lisp
(bootloader-configuration
(bootloader grub-efi-bootloader)
(target "/boot/efi"))
-@end example
+@end lisp
@xref{Bootloader Configuration}, for more information on the available
configuration options.
@@ -10588,11 +10588,11 @@ Partitioning,,, guile, GNU Guile Reference Manual}).
For instance, the
following expression returns a list that contains all the services in
@code{%desktop-services} minus the Avahi service:
-@example
+@lisp
(remove (lambda (service)
(eq? (service-kind service) avahi-service-type))
%desktop-services)
-@end example
+@end lisp
@unnumberedsubsec Instantiating the System
@@ -10753,12 +10753,12 @@ the home directory of newly-created user accounts.
For instance, a valid value may look like this:
-@example
+@lisp
`((".bashrc" ,(plain-file "bashrc" "echo Hello\n"))
(".guile" ,(plain-file "guile"
"(use-modules (ice-9 readline))
(activate-readline)")))
-@end example
+@end lisp
@item @code{issue} (default: @code{%default-issue})
A string denoting the contents of the @file{/etc/issue} file, which is
@@ -10836,14 +10836,14 @@ this identifier resolves to the operating system
being defined.
The example below shows how to refer to the operating system being defined in
the definition of the @code{label} field:
-@example
+@lisp
(use-modules (gnu) (guix))
(operating-system
;; ...
(label (package-full-name
(operating-system-kernel this-operating-system))))
-@end example
+@end lisp
It is an error to refer to @code{this-operating-system} outside an operating
system definition.
@@ -10859,12 +10859,12 @@ The list of file systems to be mounted is specified
in the
(@pxref{Using the Configuration System}). Each file system is declared
using the @code{file-system} form, like this:
-@example
+@lisp
(file-system
(mount-point "/home")
(device "/dev/sda3")
(type "ext4"))
-@end example
+@end lisp
As usual, some of the fields are mandatory---those shown in the example
above---while others can be omitted. These are described below.
@@ -10898,12 +10898,12 @@ procedure, UUIDs are created using @code{uuid}, and
@file{/dev} node are
plain strings. Here's an example of a file system referred to by its
label, as shown by the @command{e2label} command:
-@example
+@lisp
(file-system
(mount-point "/home")
(type "ext4")
(device (file-system-label "my-home")))
-@end example
+@end lisp
@findex uuid
UUIDs are converted from their string representation (as shown by the
@@ -10914,12 +10914,12 @@ form of UUID used by the ext2 family of file systems
and others, but it
is different from ``UUIDs'' found in FAT file systems, for instance.},
like this:
-@example
+@lisp
(file-system
(mount-point "/home")
(type "ext4")
(device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
-@end example
+@end lisp
When the source of a file system is a mapped device (@pxref{Mapped
Devices}), its @code{device} field @emph{must} refer to the mapped
@@ -11094,12 +11094,12 @@ The @file{/dev/mapper/home}
device can then be used as the @code{device} of a @code{file-system}
declaration (@pxref{File Systems}).
-@example
+@lisp
(mapped-device
(source "/dev/sda3")
(target "home")
(type luks-device-mapping))
-@end example
+@end lisp
Alternatively, to become independent of device numbering, one may obtain
the LUKS UUID (@dfn{unique identifier}) of the source device by a
@@ -11111,12 +11111,12 @@ cryptsetup luksUUID /dev/sda3
and use it as follows:
-@example
+@lisp
(mapped-device
(source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
(target "home")
(type luks-device-mapping))
-@end example
+@end lisp
@cindex swap encryption
It is also desirable to encrypt swap space, since swap space may contain
@@ -11128,12 +11128,12 @@ swap file is encrypted because the entire device is
encrypted.
A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1}
may be declared as follows:
-@example
+@lisp
(mapped-device
(source (list "/dev/sda1" "/dev/sdb1"))
(target "/dev/md0")
(type raid-device-mapping))
-@end example
+@end lisp
The @file{/dev/md0} device can then be used as the @code{device} of a
@code{file-system} declaration (@pxref{File Systems}).
@@ -11152,7 +11152,7 @@ User accounts and groups are entirely managed through
the
@code{operating-system} declaration. They are specified with the
@code{user-account} and @code{user-group} forms:
-@example
+@lisp
(user-account
(name "alice")
(group "users")
@@ -11162,7 +11162,7 @@ User accounts and groups are entirely managed through
the
"cdrom")) ;the good ol' CD-ROM
(comment "Bob's sister")
(home-directory "/home/alice"))
-@end example
+@end lisp
When booting or upon completion of @command{guix system reconfigure},
the system ensures that only the user accounts and groups specified in
@@ -11226,14 +11226,14 @@ If you @emph{do} want to set an initial password for
an account, then
this field must contain the encrypted password, as a string. You can use the
@code{crypt} procedure for this purpose:
-@example
+@lisp
(user-account
(name "charlie")
(group "users")
;; Specify a SHA-512-hashed initial password.
(password (crypt "InitialPassword!" "$6$abc")))
-@end example
+@end lisp
@quotation Note
The hash of this initial password will be available in a file in
@@ -11251,9 +11251,9 @@ Guile Reference Manual}, for information on Guile's
@code{crypt} procedure.
@cindex groups
User group declarations are even simpler:
-@example
+@lisp
(user-group (name "students"))
-@end example
+@end lisp
@deftp {Data Type} user-group
This type is for, well, user groups. There are just a few fields:
@@ -11340,7 +11340,7 @@ optional variant name, an optional keyboard model name,
and a possibly empty
list of additional options. In most cases the layout name is all you care
about. Here are a few example:
-@example
+@lisp
;; The German QWERTZ layout. Here we assume a standard
;; "pc105" keyboard model.
(keyboard-layout "de")
@@ -11365,7 +11365,7 @@ about. Here are a few example:
;; dead keys to enter accented characters. This is for an
;; Apple MacBook keyboard.
(keyboard-layout "us" "intl" #:model "macbook78")
-@end example
+@end lisp
See the @file{share/X11/xkb} directory of the @code{xkeyboard-config} package
for a complete list of supported layouts, variants, and models.
@@ -11455,20 +11455,20 @@ used locales, but not all the available locales, in
order to save space.
For instance, to add the North Frisian locale for Germany, the value of
that field may be:
-@example
+@lisp
(cons (locale-definition
(name "fy_DE.utf8") (source "fy_DE"))
%default-locale-definitions)
-@end example
+@end lisp
Likewise, to save space, one might want @code{locale-definitions} to
list only the locales that are actually used, as in:
-@example
+@lisp
(list (locale-definition
(name "ja_JP.eucjp") (source "ja_JP")
(charset "EUC-JP")))
-@end example
+@end lisp
@vindex LOCPATH
The compiled locale definitions are available at
@@ -11554,13 +11554,13 @@ it---this is especially crucial on a multi-user
system. To do that, the
administrator can specify several libc packages in the
@code{locale-libcs} field of @code{operating-system}:
-@example
+@lisp
(use-package-modules base)
(operating-system
;; @dots{}
(locale-libcs (list glibc-2.21 (canonical-package glibc))))
-@end example
+@end lisp
This example would lead to a system containing locale definitions for
both libc 2.21 and the current version of libc in
@@ -11665,11 +11665,11 @@ This is the default value of the @code{services}
field of
system, you will want to append services to @code{%base-services}, like
this:
-@example
+@lisp
(append (list (service avahi-service-type)
(service openssh-service-type))
%base-services)
-@end example
+@end lisp
@end defvr
@defvr {Scheme Variable} special-files-service-type
@@ -11682,19 +11682,19 @@ and the second element is its target. By default it
is:
@cindex @file{/bin/sh}
@cindex @file{sh}, in @file{/bin}
-@example
-`(("/bin/sh" ,(file-append @var{bash} "/bin/sh")))
-@end example
+@lisp
+`(("/bin/sh" ,(file-append bash "/bin/sh")))
+@end lisp
@cindex @file{/usr/bin/env}
@cindex @file{env}, in @file{/usr/bin}
If you want to add, say, @code{/usr/bin/env} to your system, you can
change it to:
-@example
-`(("/bin/sh" ,(file-append @var{bash} "/bin/sh"))
- ("/usr/bin/env" ,(file-append @var{coreutils} "/bin/env")))
-@end example
+@lisp
+`(("/bin/sh" ,(file-append bash "/bin/sh"))
+ ("/usr/bin/env" ,(file-append coreutils "/bin/env")))
+@end lisp
Since this is part of @code{%base-services}, you can use
@code{modify-services} to customize the set of special files
@@ -11710,10 +11710,10 @@ For example, adding the following lines to the
@code{services} field of
your operating system declaration leads to a @file{/usr/bin/env}
symlink:
-@example
+@lisp
(extra-special-file "/usr/bin/env"
(file-append coreutils "/bin/env"))
-@end example
+@end lisp
@end deffn
@deffn {Scheme Procedure} host-name-service @var{name}
@@ -12212,14 +12212,14 @@ In the following example, a rule for a USB device is
defined to be
stored in the file @file{90-usb-thing.rules}. The rule runs a script
upon detecting a USB device with a given product identifier.
-@example
+@lisp
(define %example-udev-rule
(udev-rule
"90-usb-thing.rules"
(string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", "
"ATTR@{product@}==\"Example\", "
"RUN+=\"/path/to/script\"")))
-@end example
+@end lisp
The @command{herd rules udev} command, as root, returns the name of the
directory containing all the active udev rules.
@@ -12227,7 +12227,7 @@ directory containing all the active udev rules.
Here we show how the default @var{udev-service} can be extended with it.
-@example
+@lisp
(operating-system
;; @dots{}
(services
@@ -12236,7 +12236,7 @@ Here we show how the default @var{udev-service} can be
extended with it.
(udev-configuration (inherit config)
(rules (append (udev-configuration-rules config)
(list %example-udev-rule))))))))
-@end example
+@end lisp
@deffn {Scheme Procedure} file->udev-rule [@var{file-name} @var{file}]
Return a udev file named @var{file-name} containing the rules defined
@@ -12244,7 +12244,7 @@ within @var{file}, a file-like object.
The following example showcases how we can use an existing rule file.
-@example
+@lisp
(use-modules (guix download) ;for url-fetch
(guix packages) ;for origin
;; @dots{})
@@ -12259,7 +12259,7 @@ The following example showcases how we can use an
existing rule file.
"android-udev-rules/" version "/51-android.rules"))
(sha256
(base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003"))))))
-@end example
+@end lisp
@end deffn
Additionally, Guix package definitions can be included in @var{rules} in
@@ -12278,7 +12278,7 @@ 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.
-@example
+@lisp
(use-modules (gnu packages android) ;for android-udev-rules
(gnu system shadow) ;for user-group
;; @dots{})
@@ -12304,7 +12304,7 @@ well as in the @var{groups} field of the
@var{operating-system} record.
(udev-configuration (inherit config)
(rules (cons android-udev-rules
(udev-configuration-rules config))))))))
-@end example
+@end lisp
@defvr {Scheme Variable} urandom-seed-service-type
Save some entropy in @var{%random-seed-file} to seed @file{/dev/urandom}
@@ -12378,9 +12378,9 @@ This is a list of compression method/level tuple used
when compressing
substitutes. For example, to compress all substitutes with @emph{both} lzip
at level 7 and gzip at level 9, write:
-@example
+@lisp
'(("lzip" 7) ("gzip" 9))
-@end example
+@end lisp
Level 9 achieves the best compression ratio at the expense of increased CPU
usage, whereas level 1 achieves fast compression.
@@ -12435,12 +12435,12 @@ Return a service that installs a configuration file
for the
The following limits definition sets two hard and soft limits for all
login sessions of users in the @code{realtime} group:
-@example
+@lisp
(pam-limits-service
(list
(pam-limits-entry "@@realtime" 'both 'rtprio 99)
(pam-limits-entry "@@realtime" 'both 'memlock 'unlimited)))
-@end example
+@end lisp
The first entry increases the maximum realtime priority for
non-privileged processes; the second entry lifts any restriction of the
@@ -12647,7 +12647,7 @@ Taking an example from the Rottlog manual
(@pxref{Period Related File
Examples,,, rottlog, GNU Rot[t]log Manual}), a log rotation might be
defined like this:
-@example
+@lisp
(log-rotation
(frequency 'daily)
(files '("/var/log/apache/*"))
@@ -12655,7 +12655,7 @@ defined like this:
"rotate 6"
"notifempty"
"nocompress")))
-@end example
+@end lisp
The list of fields is as follows:
@@ -12704,12 +12704,12 @@ This type defines a service that runs a DHCP daemon.
To create a
service of this type, you must supply a @code{<dhcpd-configuration>}.
For example:
-@example
+@lisp
(service dhcpd-service-type
(dhcpd-configuration
(config-file (local-file "my-dhcpd.conf"))
(interfaces '("enp0s25"))))
-@end example
+@end lisp
@end deffn
@deftp {Data Type} dhcpd-configuration
@@ -12765,11 +12765,11 @@ to handle.
For example:
-@example
+@lisp
(static-networking-service "eno1" "192.168.1.82"
#:gateway "192.168.1.2"
#:name-servers '("192.168.1.2"))
-@end example
+@end lisp
@end deffn
@cindex wicd
@@ -12924,11 +12924,11 @@ a network connection manager.
Its value must be an
@code{connman-configuration} record as in this example:
-@example
+@lisp
(service connman-service-type
(connman-configuration
(disable-vpn? #t)))
-@end example
+@end lisp
See below for details about @code{connman-configuration}.
@end deffn
@@ -13066,7 +13066,7 @@ Run the @command{ntpd}, the Network Time Protocol (NTP)
daemon, as implemented
by @uref{http://www.openntpd.org, OpenNTPD}. The daemon will keep the system
clock synchronized with that of the given servers.
-@example
+@lisp
(service
openntpd-service-type
(openntpd-configuration
@@ -13076,7 +13076,7 @@ clock synchronized with that of the given servers.
(constraints-from '("https://www.google.com/";))
(allow-large-adjustment? #t)))
-@end example
+@end lisp
@end deffn
@deftp {Data Type} openntpd-configuration
@@ -13126,7 +13126,7 @@ built-in @command{echo} service, as well as an smtp
service which
forwards smtp traffic over ssh to a server @code{smtp-server} behind a
gateway @code{hostname}:
-@example
+@lisp
(service
inetd-service-type
(inetd-configuration
@@ -13148,7 +13148,7 @@ gateway @code{hostname}:
(arguments
'("ssh" "-qT" "-i" "/path/to/ssh_key"
"-W" "smtp-server:25" "user@@hostname")))))
-@end example
+@end lisp
See below for more details about @code{inetd-configuration}.
@end deffn
@@ -13284,9 +13284,9 @@ This is the service type for the
@uref{https://rsync.samba.org, rsync} daemon,
The value for this service type is a
@command{rsync-configuration} record as in this example:
-@example
+@lisp
(service rsync-service-type)
-@end example
+@end lisp
See below for details about @code{rsync-configuration}.
@end deffn
@@ -13390,7 +13390,7 @@ This is the type for the @uref{http://www.openssh.org,
OpenSSH} secure
shell daemon, @command{sshd}. Its value must be an
@code{openssh-configuration} record as in this example:
-@example
+@lisp
(service openssh-service-type
(openssh-configuration
(x11-forwarding? #t)
@@ -13398,18 +13398,18 @@ shell daemon, @command{sshd}. Its value must be an
(authorized-keys
`(("alice" ,(local-file "alice.pub"))
("bob" ,(local-file "bob.pub"))))))
-@end example
+@end lisp
See below for details about @code{openssh-configuration}.
This service can be extended with extra authorized keys, as in this
example:
-@example
+@lisp
(service-extension openssh-service-type
(const `(("charlie"
,(local-file "charlie.pub")))))
-@end example
+@end lisp
@end deffn
@deftp {Data Type} openssh-configuration
@@ -13486,12 +13486,12 @@ subsystem request.
The command @command{internal-sftp} implements an in-process SFTP
server. Alternately, one can specify the @command{sftp-server} command:
-@example
+@lisp
(service openssh-service-type
(openssh-configuration
(subsystems
`(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))
-@end example
+@end lisp
@item @code{accepted-environment} (default: @code{'()})
List of strings describing which environment variables may be exported.
@@ -13504,11 +13504,11 @@ It is set by terminal emulators, which support
colors. You can use it in
your shell's ressource file to enable colors for the prompt and commands
if this variable is set.
-@example
+@lisp
(service openssh-service-type
(openssh-configuration
(accepted-environment '("COLORTERM"))))
-@end example
+@end lisp
@item @code{authorized-keys} (default: @code{'()})
@cindex authorized keys, SSH
@@ -13517,13 +13517,13 @@ This is the list of authorized keys. Each element of
the list is a user
name followed by one or more file-like objects that represent SSH public
keys. For example:
-@example
+@lisp
(openssh-configuration
(authorized-keys
`(("rekado" ,(local-file "rekado.pub"))
("chris" ,(local-file "chris.pub"))
("root" ,(local-file "rekado.pub") ,(local-file "chris.pub")))))
-@end example
+@end lisp
@noindent
registers the specified public keys for user accounts @code{rekado},
@@ -13546,12 +13546,12 @@ is especially useful for elaborate configurations
that cannot be expressed
otherwise. This configuration, for example, would generally disable root
logins, but permit them from one specific IP address:
-@example
+@lisp
(openssh-configuration
(extra-content "\
Match Address 192.168.0.1
PermitRootLogin yes"))
-@end example
+@end lisp
@end table
@end deftp
@@ -13564,10 +13564,10 @@ object.
For example, to specify a Dropbear service listening on port 1234, add
this call to the operating system's @code{services} field:
-@example
+@lisp
(dropbear-service (dropbear-configuration
(port-number 1234)))
-@end example
+@end lisp
@end deffn
@deftp {Data Type} dropbear-configuration
@@ -13608,7 +13608,7 @@ This variable is typically used in the
@code{hosts-file} field of an
@code{operating-system} declaration (@pxref{operating-system Reference,
@file{/etc/hosts}}):
-@example
+@lisp
(use-modules (gnu) (guix))
(operating-system
@@ -13620,7 +13620,7 @@ This variable is typically used in the
@code{hosts-file} field of an
(plain-file "hosts"
(string-append (local-host-aliases host-name)
%facebook-host-aliases))))
-@end example
+@end lisp
This mechanism can prevent programs running locally, such as Web
browsers, from accessing Facebook.
@@ -14054,9 +14054,9 @@ system, add a @code{cups-service} to the operating
system definition:
The service type for the CUPS print server. Its value should be a valid
CUPS configuration (see below). To use the default settings, simply
write:
-@example
+@lisp
(service cups-service-type)
-@end example
+@end lisp
@end deffn
The CUPS configuration controls the basic things about your CUPS
@@ -14072,13 +14072,13 @@ support for Epson printers @i{via} the @code{escpr}
package and for HP
printers @i{via} the @code{hplip-minimal} package. You can do that directly,
like this (you need to use the @code{(gnu packages cups)} module):
-@example
+@lisp
(service cups-service-type
(cups-configuration
(web-interface? #t)
(extensions
(list cups-filters escpr hplip-minimal))))
-@end example
+@end lisp
Note: If you wish to use the Qt5 based GUI which comes with the hplip
package then it is suggested that you install the @code{hplip} package,
@@ -14886,12 +14886,12 @@ For example, if your @code{cupsd.conf} and
@code{cups-files.conf} are in
strings of the same name, you could instantiate a CUPS service like
this:
-@example
+@lisp
(service cups-service-type
(opaque-cups-configuration
(cupsd.conf cupsd.conf)
(cups-files.conf cups-files.conf)))
-@end example
+@end lisp
@node Desktop Services
@@ -15034,7 +15034,7 @@ them by default. To add GNOME, Xfce or MATE, just
@code{cons} them onto
@code{%desktop-services} in the @code{services} field of your
@code{operating-system}:
-@example
+@lisp
(use-modules (gnu))
(use-service-modules desktop)
(operating-system
@@ -15044,7 +15044,7 @@ them by default. To add GNOME, Xfce or MATE, just
@code{cons} them onto
(service xfce-desktop-service)
%desktop-services))
...)
-@end example
+@end lisp
These desktop environments will then be available as options in the
graphical login window.
@@ -15313,9 +15313,9 @@ Architecture} (ALSA) system, which generates the
@file{/etc/asound.conf}
configuration file. The value for this type is a @command{alsa-configuration}
record as in this example:
-@example
+@lisp
(service alsa-service-type)
-@end example
+@end lisp
See below for details about @code{alsa-configuration}.
@end deffn
@@ -15401,7 +15401,7 @@ to create a geographic database using the
@code{postgis} extension, a user can
configure the postgresql-service as in this example:
@cindex postgis
-@example
+@lisp
(use-package-modules databases geo)
(operating-system
@@ -15413,7 +15413,7 @@ configure the postgresql-service as in this example:
(cons*
(postgresql-service #:extension-packages (list postgis))
%base-services)))
-@end example
+@end lisp
Then the extension becomes visible and you can initialise an empty geographic
database in this way:
@@ -15461,9 +15461,9 @@ Memcached} service, which provides a distributed in
memory cache. The
value for the service type is a @code{memcached-configuration} object.
@end defvr
-@example
+@lisp
(service memcached-service-type)
-@end example
+@end lisp
@deftp {Data Type} memcached-configuration
Data type representing the configuration of memcached.
@@ -15492,9 +15492,9 @@ This is the service type for
@uref{https://www.mongodb.com/, MongoDB}.
The value for the service type is a @code{mongodb-configuration} object.
@end defvr
-@example
+@lisp
(service mongodb-service-type)
-@end example
+@end lisp
@deftp {Data Type} mongodb-configuration
Data type representing the configuration of mongodb.
@@ -15565,11 +15565,11 @@ administrator to specify these parameters via a
uniform Scheme interface.
For example, to specify that mail is located at @code{maildir~/.mail},
one would instantiate the Dovecot service like this:
-@example
+@lisp
(dovecot-service #:config
(dovecot-configuration
(mail-location "maildir:~/.mail")))
-@end example
+@end lisp
The available configuration parameters follow. Each parameter
definition is preceded by its type; for example, @samp{string-list foo}
@@ -16905,11 +16905,11 @@ The contents of the @code{dovecot.conf}, as a string.
For example, if your @code{dovecot.conf} is just the empty string, you
could instantiate a dovecot service like this:
-@example
+@lisp
(dovecot-service #:config
(opaque-dovecot-configuration
(string "")))
-@end example
+@end lisp
@subsubheading OpenSMTPD Service
@@ -16918,11 +16918,11 @@ This is the type of the
@uref{https://www.opensmtpd.org, OpenSMTPD}
service, whose value should be an @code{opensmtpd-configuration} object
as in this example:
-@example
+@lisp
(service opensmtpd-service-type
(opensmtpd-configuration
(config-file (local-file "./my-smtpd.conf"))))
-@end example
+@end lisp
@end deffn
@deftp {Data Type} opensmtpd-configuration
@@ -16952,11 +16952,11 @@ This is the type of the @uref{https://exim.org, Exim}
mail transfer
agent (MTA), whose value should be an @code{exim-configuration} object
as in this example:
-@example
+@lisp
(service exim-service-type
(exim-configuration
(config-file (local-file "./my-exim.conf"))))
-@end example
+@end lisp
@end deffn
In order to use an @code{exim-service-type} service you must also have a
@@ -17280,11 +17280,11 @@ Defaults to @samp{()}.
This is the type of the service which provides @code{/etc/aliases},
specifying how to deliver mail to users on this system.
-@example
+@lisp
(service mail-aliases-service-type
'(("postmaster" "bob")
("bob" "bob@@example.com" "bob@@example2.com")))
-@end example
+@end lisp
@end deffn
The configuration for a @code{mail-aliases-service-type} service is an
@@ -17307,11 +17307,11 @@ This is the type of the GNU Mailutils IMAP4 Daemon
(@pxref{imap4d,,,
mailutils, GNU Mailutils Manual}), whose value should be an
@code{imap4d-configuration} object as in this example:
-@example
+@lisp
(service imap4d-service-type
(imap4d-configuration
(config-file (local-file "imap4d.conf"))))
-@end example
+@end lisp
@end deffn
@deftp {Data Type} imap4d-configuration
@@ -17345,7 +17345,7 @@ This is the type for the @uref{https://prosody.im,
Prosody XMPP
communication server}. Its value must be a @code{prosody-configuration}
record as in this example:
-@example
+@lisp
(service prosody-service-type
(prosody-configuration
(modules-enabled (cons "groups" "mam" %default-modules-enabled))
@@ -17359,7 +17359,7 @@ record as in this example:
(list
(virtualhost-configuration
(domain "example.net"))))))
-@end example
+@end lisp
See below for details about @code{prosody-configuration}.
@@ -17747,11 +17747,11 @@ The contents of the @code{prosody.cfg.lua} to use.
For example, if your @code{prosody.cfg.lua} is just the empty
string, you could instantiate a prosody service like this:
-@example
+@lisp
(service prosody-service-type
(opaque-prosody-configuration
(prosody.cfg.lua "")))
-@end example
+@end lisp
@c end of Prosody auto-generated documentation
@@ -17770,9 +17770,9 @@ below).
To have BitlBee listen on port 6667 on localhost, add this line to your
services:
-@example
+@lisp
(service bitlbee-service-type)
-@end example
+@end lisp
@end defvr
@deftp {Data Type} bitlbee-configuration
@@ -17844,7 +17844,7 @@ the server of the @uref{https://mumble.info, Mumble}
voice-over-IP
The service type for the Murmur server. An example configuration can
look like this:
-@example
+@lisp
(service murmur-service-type
(murmur-configuration
(welcome-text
@@ -17852,7 +17852,7 @@ look like this:
(cert-required? #t) ;disallow text password logins
(ssl-cert "/etc/letsencrypt/live/mumble.example.com/fullchain.pem")
(ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem")))
-@end example
+@end lisp
After reconfiguring your system, you can manually set the murmur
@code{SuperUser}
password with the command that is printed during the activation phase.
@@ -17966,14 +17966,14 @@ Should logged ips be obfuscated to protect the
privacy of users.
@item @code{ssl-cert} (default: @code{#f})
File name of the SSL/TLS certificate used for encrypted connections.
-@example
+@lisp
(ssl-cert "/etc/letsencrypt/live/example.com/fullchain.pem")
-@end example
+@end lisp
@item @code{ssl-key} (default: @code{#f})
Filepath to the ssl private key used for encrypted connections.
-@example
+@lisp
(ssl-key "/etc/letsencrypt/live/example.com/privkey.pem")
-@end example
+@end lisp
@item @code{ssl-dh-params} (default: @code{#f})
File name of a PEM-encoded file with Diffie-Hellman parameters
@@ -18047,20 +18047,20 @@ viewing and searching log files.
The following example will configure the service with default values.
By default, Tailon can be accessed on port 8080 (@code{http://localhost:8080}).
-@example
+@lisp
(service tailon-service-type)
-@end example
+@end lisp
The following example customises more of the Tailon configuration,
adding @command{sed} to the list of allowed commands.
-@example
+@lisp
(service tailon-service-type
(tailon-configuration
(config-file
(tailon-configuration-file
(allowed-commands '("tail" "grep" "awk" "sed"))))))
-@end example
+@end lisp
@deftp {Data Type} tailon-configuration
@@ -18076,11 +18076,11 @@ The configuration file to use for Tailon. This can be
set to a
For example, to instead use a local file, the @code{local-file} function
can be used:
-@example
+@lisp
(service tailon-service-type
(tailon-configuration
(config-file (local-file "./my-tailon.conf"))))
-@end example
+@end lisp
@item @code{package} (default: @code{tailon})
The tailon package to use.
@@ -18136,12 +18136,12 @@ restricted to the credentials provided here. To
configure users, use a
list of pairs, where the first element of the pair is the username, and
the 2nd element of the pair is the password.
-@example
+@lisp
(tailon-configuration-file
(http-auth "basic")
(users '(("user1" . "password1")
("user2" . "password2"))))
-@end example
+@end lisp
@end table
@end deftp
@@ -18158,11 +18158,11 @@ This is the service type for the
service, its value must be a @code{darkstat-configuration} record as in
this example:
-@example
+@lisp
(service darkstat-service-type
(darkstat-configuration
(interface "eno1")))
-@end example
+@end lisp
@end defvar
@deftp {Data Type} darkstat-configuration
@@ -18202,11 +18202,11 @@ This is the service type for the
service, its value must be a @code{prometheus-node-exporter-configuration}
record as in this example:
-@example
+@lisp
(service prometheus-node-exporter-service-type
(prometheus-node-exporter-configuration
(web-listen-address ":9100")))
-@end example
+@end lisp
@end defvar
@deftp {Data Type} prometheus-node-exporter-configuration
@@ -18682,7 +18682,7 @@ Here is a simple operating system declaration with a
default configuration of
the @code{nslcd-service-type} and a Name Service Switch configuration that
consults the @code{ldap} name service last:
-@example
+@lisp
(use-service-modules authentication)
(use-modules (gnu system nss))
...
@@ -18704,7 +18704,7 @@ consults the @code{ldap} name service last:
(group services)
(netgroup services)
(gshadow services)))))
-@end example
+@end lisp
@c %start of generated documentation for nslcd-configuration
@@ -19163,19 +19163,19 @@ Service type for the
@uref{https://httpd.apache.org/,Apache HTTP} server
A simple example configuration is given below.
-@example
+@lisp
(service httpd-service-type
(httpd-configuration
(config
(httpd-config-file
(server-name "www.example.com")
(document-root "/srv/http/www.example.com")))))
-@end example
+@end lisp
Other services can also extend the @code{httpd-service-type} to add to
the configuration.
-@example
+@lisp
(simple-service 'my-extra-server httpd-service-type
(list
(httpd-virtualhost
@@ -19183,7 +19183,7 @@ the configuration.
(list (string-append
"ServerName "www.example.com
DocumentRoot \"/srv/http/www.example.com\"")))))
-@end example
+@end lisp
@end deffn
The details for the @code{httpd-configuration}, @code{httpd-module},
@@ -19240,7 +19240,7 @@ additional configuration.
For example, in order to handle requests for PHP files, you can use Apache’s
@code{mod_proxy_fcgi} module along with @code{php-fpm-service-type}:
-@example
+@lisp
(service httpd-service-type
(httpd-configuration
(config
@@ -19261,7 +19261,7 @@ For example, in order to handle requests for PHP files,
you can use Apache’s
(php-fpm-configuration
(socket "/var/run/php-fpm.sock")
(socket-group "httpd")))
-@end example
+@end lisp
@item @code{server-root} (default: @code{httpd})
The @code{ServerRoot} in the configuration file, defaults to the httpd
@@ -19315,7 +19315,7 @@ This data type represents a virtualhost configuration
block for the httpd servic
These should be added to the extra-config for the httpd-service.
-@example
+@lisp
(simple-service 'my-extra-server httpd-service-type
(list
(httpd-virtualhost
@@ -19323,7 +19323,7 @@ These should be added to the extra-config for the
httpd-service.
(list (string-append
"ServerName "www.example.com
DocumentRoot \"/srv/http/www.example.com\"")))))
-@end example
+@end lisp
@table @asis
@item @code{addresses-and-ports}
@@ -19344,25 +19344,25 @@ value for this service type is a
@code{<nginx-configuration>} record.
A simple example configuration is given below.
-@example
+@lisp
(service nginx-service-type
(nginx-configuration
(server-blocks
(list (nginx-server-configuration
(server-name '("www.example.com"))
(root "/srv/http/www.example.com"))))))
-@end example
+@end lisp
In addition to adding server blocks to the service configuration
directly, this service can be extended by other services to add server
blocks, as in this example:
-@example
+@lisp
(simple-service 'my-extra-server nginx-service-type
(list (nginx-server-configuration
(root "/srv/http/extra-website")
(try-files (list "$uri" "$uri/index.html")))))
-@end example
+@end lisp
@end deffn
At startup, @command{nginx} has not yet read its configuration file, so
@@ -19398,14 +19398,14 @@ file, the elements should be of type
The following example would setup NGinx to serve @code{www.example.com}
from the @code{/srv/http/www.example.com} directory, without using
HTTPS.
-@example
+@lisp
(service nginx-service-type
(nginx-configuration
(server-blocks
(list (nginx-server-configuration
(server-name '("www.example.com"))
(root "/srv/http/www.example.com"))))))
-@end example
+@end lisp
@item @code{upstream-blocks} (default: @code{'()})
A list of @dfn{upstream blocks} to create in the generated configuration
@@ -19419,7 +19419,7 @@ creates a server configuration with one location
configuration, that
will proxy requests to a upstream configuration, which will handle
requests with two servers.
-@example
+@lisp
(service
nginx-service-type
(nginx-configuration
@@ -19437,7 +19437,7 @@ requests with two servers.
(name "server-proxy")
(servers (list "server1.example.com"
"server2.example.com")))))))
-@end example
+@end lisp
@item @code{file} (default: @code{#f})
If a configuration @var{file} is provided, this will be used, rather than
@@ -19475,9 +19475,9 @@ path for a UNIX-domain socket on which the server will
accept requests.
Both address and port, or only address or only port can be specified.
An address may also be a hostname, for example:
-@example
+@lisp
'("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000")
-@end example
+@end lisp
@item @code{server-name} (default: @code{(list 'default)})
A list of server names this server represents. @code{'default} represents the
@@ -19615,7 +19615,7 @@ VCL syntax.
For example, to mirror @url{http://www.gnu.org,www.gnu.org} with VCL you
can do something along these lines:
-@example
+@lisp
(define %gnu-mirror
(plain-file
"gnu.vcl"
@@ -19629,7 +19629,7 @@ backend gnu @{ .host = "www.gnu.org"; @}"))
(listen '(":80"))
(vcl %gnu-mirror)))
%base-services)))
-@end example
+@end lisp
The configuration of an already running Varnish instance can be inspected
and changed using the @command{varnishadm} program.
@@ -19665,7 +19665,7 @@ Service type for Patchwork.
The following example is an example of a minimal service for Patchwork, for
the @code{patchwork.example.com} domain.
-@example
+@lisp
(service patchwork-service-type
(patchwork-configuration
(domain "patchwork.example.com")
@@ -19685,7 +19685,7 @@ the @code{patchwork.example.com} domain.
(extra-parameters
'((mailboxes . ("Patches"))))))))
-@end example
+@end lisp
There are three records for configuring the Patchwork service. The
@code{<patchwork-configuration>} relates to the configuration for Patchwork
@@ -20004,7 +20004,7 @@ A helper function to quickly add php to an
@code{nginx-server-configuration}.
@end deffn
A simple services setup for nginx with php can look like this:
-@example
+@lisp
(services (cons* (service dhcp-client-service-type)
(service php-fpm-service-type)
(service nginx-service-type
@@ -20017,7 +20017,7 @@ A simple services setup for nginx with php can look
like this:
(ssl-certificate #f)
(ssl-certificate-key #f)))
%base-services))
-@end example
+@end lisp
@cindex cat-avatar-generator
The cat avatar generator is a simple service to demonstrate the use of php-fpm
@@ -20035,14 +20035,14 @@ be able to use @code{cache-dir} as its cache
directory.
@end deffn
A simple setup for cat-avatar-generator can look like this:
-@example
+@lisp
(services (cons* (cat-avatar-generator-service
#:configuration
(nginx-server-configuration
(server-name '("example.com"))))
...
%base-services))
-@end example
+@end lisp
@subsubheading Hpcguix-web
@@ -20099,7 +20099,7 @@ The hpcguix-web package to use.
A typical hpcguix-web service declaration looks like this:
-@example
+@lisp
(service hpcguix-web-service-type
(hpcguix-web-configuration
(specs
@@ -20107,7 +20107,7 @@ A typical hpcguix-web service declaration looks like
this:
(hpcweb-configuration
(title-prefix "Guix-HPC - ")
(menu '(("/about" "ABOUT"))))))))
-@end example
+@end lisp
@quotation Note
The hpcguix-web service periodically updates the package list it publishes by
@@ -20167,7 +20167,7 @@ can be found there:
A service type for the @code{certbot} Let's Encrypt client. Its value
must be a @code{certbot-configuration} record as in this example:
-@example
+@lisp
(define %nginx-deploy-hook
(program-file
"nginx-deploy-hook"
@@ -20184,7 +20184,7 @@ must be a @code{certbot-configuration} record as in
this example:
(deploy-hook %nginx-deploy-hook))
(certificate-configuration
(domains '("bar.example.net")))))))
-@end example
+@end lisp
See below for details about @code{certbot-configuration}.
@end defvr
@@ -20766,12 +20766,12 @@ The list of knot-zone-configuration used by this
configuration.
This is the type of the dnsmasq service, whose value should be an
@code{dnsmasq-configuration} object as in this example:
-@example
+@lisp
(service dnsmasq-service-type
(dnsmasq-configuration
(no-resolv? #t)
(servers '("192.168.1.1"))))
-@end example
+@end lisp
@end deffn
@deftp {Data Type} dnsmasq-configuration
@@ -20824,9 +20824,9 @@ care of automatically updating DNS entries for service
providers such as
The following example show instantiates the service with its default
configuration:
-@example
+@lisp
(service ddclient-service-type)
-@end example
+@end lisp
Note that ddclient needs to access credentials that are stored in a
@dfn{secret file}, by default @file{/etc/ddclient/secrets} (see
@@ -21416,7 +21416,7 @@ and builds the packages from a manifest. Some of the
packages are defined in
the @code{"custom-packages"} input, which is the equivalent of
@code{GUIX_PACKAGE_PATH}.
-@example
+@lisp
(define %cuirass-specs
#~(list
'((#:name . "my-manifest")
@@ -21447,7 +21447,7 @@ the @code{"custom-packages"} input, which is the
equivalent of
(service cuirass-service-type
(cuirass-configuration
(specifications %cuirass-specs)))
-@end example
+@end lisp
While information related to build jobs is located directly in the
specifications, global settings for the @command{cuirass} process are
@@ -21535,9 +21535,9 @@ source is detected. More information can be found at
The service type for the TLP tool. Its value should be a valid
TLP configuration (see below). To use the default settings, simply
write:
-@example
+@lisp
(service tlp-service-type)
-@end example
+@end lisp
@end deffn
By default TLP does not need much configuration but most TLP parameters
@@ -22065,12 +22065,12 @@ of clients.
The following example shows how one might run @code{mpd} as user
@code{"bob"} on port @code{6666}. It uses pulseaudio for output.
-@example
+@lisp
(service mpd-service-type
(mpd-configuration
(user "bob")
(port "6666")))
-@end example
+@end lisp
@defvr {Scheme Variable} mpd-service-type
The service type for @command{mpd}
@@ -22124,12 +22124,12 @@ and performs required management tasks for
virtualized guests.
This is the type of the @uref{https://libvirt.org, libvirt daemon}.
Its value must be a @code{libvirt-configuration}.
-@example
+@lisp
(service libvirt-service-type
(libvirt-configuration
(unix-sock-group "libvirt")
(tls-port "16555")))
-@end example
+@end lisp
@end deffn
@c Auto-generated with (generate-libvirt-documentation)
@@ -22690,11 +22690,11 @@ itself upon receiving @code{SIGUSR1}, to allow live
upgrades without downtime.
This is the type of the virtlog daemon.
Its value must be a @code{virtlog-configuration}.
-@example
+@lisp
(service virtlog-service-type
(virtlog-configuration
(max-clients 1000)))
-@end example
+@end lisp
@end deffn
@deftypevr {@code{virtlog-configuration} parameter} integer log-level
@@ -22832,11 +22832,11 @@ Its value must be a @code{qemu-binfmt-configuration}
object, which
specifies the QEMU package to use as well as the architecture we want to
emulated:
-@example
+@lisp
(service qemu-binfmt-service-type
(qemu-binfmt-configuration
(platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el"))))
-@end example
+@end lisp
In this example, we enable transparent emulation for the ARM and aarch64
platforms. Running @code{herd stop qemu-binfmt} turns it off, and
@@ -22862,12 +22862,12 @@ that you can transparently build programs for another
architecture.
For example, let's suppose you're on an x86_64 machine and you have this
service:
-@example
+@lisp
(service qemu-binfmt-service-type
(qemu-binfmt-configuration
(platforms (lookup-qemu-platforms "arm"))
(guix-support? #t)))
-@end example
+@end lisp
You can run:
@@ -23018,7 +23018,7 @@ Compute an @code{nginx-location-configuration} that
corresponds to the
given Git http configuration. An example nginx service definition to
serve the default @file{/srv/git} over HTTPS might be:
-@example
+@lisp
(service nginx-service-type
(nginx-configuration
(server-blocks
@@ -23034,7 +23034,7 @@ serve the default @file{/srv/git} over HTTPS might be:
(list
(git-http-nginx-location-configuration
(git-http-configuration (uri-path "/"))))))))))
-@end example
+@end lisp
This example assumes that you are using Let's Encrypt to get your TLS
certificate. @xref{Certificate Services}. The default @code{certbot}
@@ -23053,9 +23053,9 @@ repositories written in C.
The following example will configure the service with default values.
By default, Cgit can be accessed on port 80 (@code{http://localhost:80}).
-@example
+@lisp
(service cgit-service-type)
-@end example
+@end lisp
The @code{file-object} type designates either a file-like object
(@pxref{G-Expressions, file-like objects}) or a string.
@@ -23988,11 +23988,11 @@ The contents of the @code{cgitrc}, as a string.
For example, if your @code{cgitrc} is just the empty string, you
could instantiate a cgit service like this:
-@example
+@lisp
(service cgit-service-type
(opaque-cgit-configuration
(cgitrc "")))
-@end example
+@end lisp
@subsubheading Gitolite Service
@@ -24007,13 +24007,13 @@ configuration of the permissions for the users on the
repositories.
The following example will configure Gitolite using the default @code{git}
user, and the provided SSH public key.
-@example
+@lisp
(service gitolite-service-type
(gitolite-configuration
(admin-pubkey (plain-file
"yourname.pub"
"ssh-rsa AAAA... guix@@example.com"))))
-@end example
+@end lisp
Gitolite is configured through a special admin repository which you can clone,
for example, if you setup Gitolite on @code{example.com}, you would run the
@@ -24056,9 +24056,9 @@ within the gitolite-admin repository.
To specify the SSH key as a string, use the @code{plain-file} function.
-@example
+@lisp
(plain-file "yourname.pub" "ssh-rsa AAAA... guix@@example.com")
-@end example
+@end lisp
@end table
@end deftp
@@ -24103,9 +24103,9 @@ Service type for the wesnothd service. Its value must
be a
@code{wesnothd-configuration} object. To run wesnothd in the default
configuration, instantiate it as:
-@example
+@lisp
(service wesnothd-service-type)
-@end example
+@end lisp
@end defvar
@deftp {Data Type} wesnothd-configuration
@@ -24133,9 +24133,9 @@ read and identify fingerprints via a fingerprint sensor.
The service type for @command{fprintd}, which provides the fingerprint
reading capability.
-@example
+@lisp
(service fprintd-service-type)
-@end example
+@end lisp
@end defvr
@cindex sysctl
@@ -24149,11 +24149,11 @@ The service type for @command{sysctl}, which modifies
kernel parameters
under @file{/proc/sys/}. To enable IPv4 forwarding, it can be
instantiated as:
-@example
+@lisp
(service sysctl-service-type
(sysctl-configuration
(settings '(("net.ipv4.ip_forward" . "1")))))
-@end example
+@end lisp
@end defvr
@deftp {Data Type} sysctl-configuration
@@ -24182,9 +24182,9 @@ Service type for the @command{pcscd} service. Its
value must be a
@code{pcscd-configuration} object. To run pcscd in the default
configuration, instantiate it as:
-@example
+@lisp
(service pcscd-service-type)
-@end example
+@end lisp
@end defvr
@deftp {Data Type} pcscd-configuration
@@ -24339,7 +24339,7 @@ Dictionary of English using the @code{gcide} package.
The following is an example @code{dicod-service} configuration.
-@example
+@lisp
(dicod-service #:config
(dicod-configuration
(handlers (list (dicod-handler
@@ -24353,7 +24353,7 @@ The following is an example @code{dicod-service}
configuration.
(handler "wordnet")
(options '("database=wn")))
%dicod-database:gcide))))
-@end example
+@end lisp
@cindex Docker
@subsubheading Docker Service
@@ -24453,7 +24453,7 @@ This is the type of the service that runs build daemon
of the
@url{https://nixos.org/nix/, Nix} package manager. Here is an example showing
how to use it:
-@example
+@lisp
(use-modules (gnu))
(use-service-modules nix)
(use-package-modules package-management)
@@ -24465,7 +24465,7 @@ how to use it:
(services (append (list (service nix-service-type))
%base-services)))
-@end example
+@end lisp
After @command{guix system reconfigure} configure Nix for your user:
@@ -24620,7 +24620,7 @@ As an example, the declaration below configures the NSS
to use the
back-end}, which supports host name lookups over multicast DNS (mDNS)
for host names ending in @code{.local}:
-@example
+@lisp
(name-service-switch
(hosts (list %files ;first, check /etc/hosts
@@ -24642,7 +24642,7 @@ for host names ending in @code{.local}:
;; Finally, try with the "full" 'mdns'.
(name-service
(name "mdns")))))
-@end example
+@end lisp
Do not worry: the @code{%mdns-host-lookup-nss} variable (see below)
contains this configuration, so you will not have to type it if all you
@@ -24723,10 +24723,10 @@ An action specified using the
@code{lookup-specification} macro
(@pxref{Actions in the NSS configuration,,, libc, The GNU C Library
Reference Manual}). For example:
-@example
+@lisp
(lookup-specification (unavailable => continue)
(success => return))
-@end example
+@end lisp
@end table
@end deftp
@@ -24750,11 +24750,11 @@ most use cases. For example, assuming you need the
@code{megaraid_sas}
module in addition to the default modules to be able to access your root
file system, you would write:
-@example
+@lisp
(operating-system
;; @dots{}
(initrd-modules (cons "megaraid_sas" %base-initrd-modules)))
-@end example
+@end lisp
@defvr {Scheme Variable} %base-initrd-modules
This is the list of kernel modules included in the initrd by default.
@@ -24772,14 +24772,14 @@ For example, if you want to add a bunch of kernel
modules to be loaded
at boot time, you can define the @code{initrd} field of the operating
system declaration like this:
-@example
+@lisp
(initrd (lambda (file-systems . rest)
;; Create a standard initrd but set up networking
;; with the parameters QEMU expects by default.
(apply base-initrd file-systems
#:qemu-networking? #t
rest)))
-@end example
+@end lisp
The @code{base-initrd} procedure also handles common use cases that
involves using the system as a QEMU guest, or as a ``live'' system with
@@ -25031,13 +25031,13 @@ Should you want to list additional boot menu entries
@i{via} the
boot another distro (hard to imagine!), you can define a menu entry
along these lines:
-@example
+@lisp
(menu-entry
(label "The Other Distro")
(linux "/boot/old/vmlinux-2.6.32")
(linux-arguments '("root=/dev/sda2"))
(initrd "/boot/old/initrd"))
-@end example
+@end lisp
Details below.
@@ -25052,9 +25052,9 @@ The label to show in the menu---e.g., @code{"GNU"}.
@item @code{linux}
The Linux kernel image to boot, for example:
-@example
+@lisp
(file-append linux-libre "/bzImage")
-@end example
+@end lisp
For GRUB, it is also possible to specify a device explicitly in the
file path using GRUB's device naming convention (@pxref{Naming
@@ -25590,7 +25590,7 @@ guix deploy @var{file}
Such an invocation will deploy the machines that the code within @var{file}
evaluates to. As an example, @var{file} might contain a definition like this:
-@example
+@lisp
;; This is a Guix deployment of a "bare bones" setup, with
;; no X11 display server, to a machine with an SSH daemon
;; listening on localhost:2222. A configuration such as this
@@ -25630,7 +25630,7 @@ evaluates to. As an example, @var{file} might contain
a definition like this:
(user "alice")
(identity "./id_rsa")
(port 2222)))))
-@end example
+@end lisp
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
@@ -25919,7 +25919,7 @@ A @dfn{service type} is a node in the DAG described
above. Let us start
with a simple example, the service type for the Guix build daemon
(@pxref{Invoking guix-daemon}):
-@example
+@lisp
(define guix-service-type
(service-type
(name 'guix)
@@ -25928,7 +25928,7 @@ with a simple example, the service type for the Guix
build daemon
(service-extension account-service-type guix-accounts)
(service-extension activation-service-type guix-activation)))
(default-value (guix-configuration))))
-@end example
+@end lisp
@noindent
It defines three things:
@@ -25972,12 +25972,12 @@ booted.
A service of this type is instantiated like this:
-@example
+@lisp
(service guix-service-type
(guix-configuration
(build-accounts 5)
(use-substitutes? #f)))
-@end example
+@end lisp
The second argument to the @code{service} form is a value representing
the parameters of this specific service instance.
@@ -25986,9 +25986,9 @@ information about the @code{guix-configuration} data
type. When the
value is omitted, the default value specified by
@code{guix-service-type} is used:
-@example
+@lisp
(service guix-service-type)
-@end example
+@end lisp
@code{guix-service-type} is quite simple because it extends other
services but is not extensible itself.
@@ -25997,7 +25997,7 @@ services but is not extensible itself.
The service type for an @emph{extensible} service looks like this:
-@example
+@lisp
(define udev-service-type
(service-type (name 'udev)
(extensions
@@ -26011,7 +26011,7 @@ The service type for an @emph{extensible} service looks
like this:
(udev-configuration
(udev udev) ;the udev package to use
(rules (append initial-rules rules)))))))))
-@end example
+@end lisp
This is the service type for the
@uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device
@@ -26068,17 +26068,17 @@ raised.
For instance, this:
-@example
+@lisp
(service openssh-service-type)
-@end example
+@end lisp
@noindent
is equivalent to this:
-@example
+@lisp
(service openssh-service-type
(openssh-configuration))
-@end example
+@end lisp
In both cases the result is an instance of @code{openssh-service-type}
with the default configuration.
@@ -26099,7 +26099,7 @@ parameters.
Here is an example of how a service is created and manipulated:
-@example
+@lisp
(define s
(service nginx-service-type
(nginx-configuration
@@ -26113,7 +26113,7 @@ Here is an example of how a service is created and
manipulated:
(eq? (service-kind s) nginx-service-type)
@result{} #t
-@end example
+@end lisp
The @code{modify-services} form provides a handy way to change the
parameters of some of the services of a list such as
@@ -26215,10 +26215,10 @@ service is an instance.
For example, this extends mcron (@pxref{Scheduled Job Execution}) with
an additional job:
-@example
+@lisp
(simple-service 'my-mcron-job mcron-service-type
#~(job '(next-hour (3)) "guix gc -F 2G"))
-@end example
+@end lisp
@end deffn
At the core of the service abstraction lies the @code{fold-services}
@@ -26253,9 +26253,9 @@ The type of the @file{/etc} service. This service is
used to create
files under @file{/etc} and can be extended by
passing it name/file tuples such as:
-@example
+@lisp
(list `("issue" ,(plain-file "issue" "Welcome!\n")))
-@end example
+@end lisp
In this example, the effect would be to add an @file{/etc/issue} file
pointing to the given file.
@@ -26391,7 +26391,7 @@ shepherd, The GNU Shepherd Manual}).
The following example defines an action called @code{say-hello} that kindly
greets the user:
-@example
+@lisp
(shepherd-action
(name 'say-hello)
(documentation "Say hi!")
@@ -26399,7 +26399,7 @@ greets the user:
(format #t "Hello, friend! arguments: ~s\n"
args)
#t)))
-@end example
+@end lisp
Assuming this action is added to the @code{example} service, then you can do:
@@ -26606,13 +26606,13 @@ Bash, say @code{bash-fixed}, in the usual way
(@pxref{Defining
Packages}). Then, the original package definition is augmented with a
@code{replacement} field pointing to the package containing the bug fix:
-@example
+@lisp
(define bash
(package
(name "bash")
;; @dots{}
(replacement bash-fixed)))
-@end example
+@end lisp
From there on, any package depending directly or indirectly on Bash---as
reported by @command{guix gc --requisites} (@pxref{Invoking guix