diff options
| -rw-r--r-- | doc/contributing.texi | 16 | ||||
| -rw-r--r-- | doc/guix.texi | 642 |
2 files changed, 329 insertions, 329 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 59917193f1..655c8283e5 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 6d6a09b36b..83f791d71d 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 |