Copyright @copyright{} 2015, 2016 Mathieu Lirzin@*
Copyright @copyright{} 2014 Pierre-Antoine Rault@*
Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
-Copyright @copyright{} 2015, 2016, 2017, 2019 Leo Famulari@*
+Copyright @copyright{} 2015, 2016, 2017, 2019, 2020 Leo Famulari@*
Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@*
-Copyright @copyright{} 2016, 2017, 2018, 2019 Efraim Flashner@*
+Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
Copyright @copyright{} 2016, 2017 ng0@*
Copyright @copyright{} 2016, 2017, 2018, 2019 Jan Nieuwenhuizen@*
Copyright @copyright{} 2020 Damien Cassou@*
Copyright @copyright{} 2020 Jakub Kądziołka@*
Copyright @copyright{} 2020 Jack Hill@*
+Copyright @copyright{} 2020 Naga Malleswari@*
+Copyright @copyright{} 2020 Brice Waegeneire@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
Note that the @code{glibc-locales} package contains data for all the
locales supported by the GNU@tie{}libc and weighs in at around
-110@tie{}MiB. Alternatively, the @code{glibc-utf8-locales} is smaller but
+917@tie{}MiB. Alternatively, the @code{glibc-utf8-locales} is smaller but
limited to a few UTF-8 locales.
The @code{GUIX_LOCPATH} variable plays a role similar to @code{LOCPATH}
Essential font packages include @code{gs-fonts}, @code{font-dejavu}, and
@code{font-gnu-freefont-ttf}.
+@cindex @code{fc-cache}
+@cindex font cache
+Once you have installed or removed fonts, or when you notice an
+application that does not find fonts, you may need to install Fontconfig
+and to force an update of its font cache by running:
+
+@example
+guix install fontconfig
+fc-cache -rv
+@end example
+
To display text written in Chinese languages, Japanese, or Korean in
graphical applications, consider installing
@code{font-adobe-source-han-sans} or @code{font-wqy-zenhei}. The former
After that, you can run @code{xlsfonts} (from @code{xlsfonts} package)
to make sure your TrueType fonts are listed there.
-@cindex @code{fc-cache}
-@cindex font cache
-After installing fonts you may have to refresh the font cache to use
-them in applications. The same applies when applications installed via
-Guix do not seem to find fonts. To force rebuilding of the font cache
-run @code{fc-cache -rv}. The @code{fc-cache} command is provided by
-the @code{fontconfig} package.
@subsection X.509 Certificates
@subsection Emacs Packages
@cindex @code{emacs}
-When you install Emacs packages with Guix, the elisp files may be placed
-either in @file{$HOME/.guix-profile/share/emacs/site-lisp/} or in
-sub-directories of
-@file{$HOME/.guix-profile/share/emacs/site-lisp/guix.d/}. The latter
-directory exists because potentially there may exist thousands of Emacs
-packages and storing all their files in a single directory may not be
-reliable (because of name conflicts). So we think using a separate
-directory for each package is a good idea. It is very similar to how
-the Emacs package system organizes the file structure (@pxref{Package
-Files,,, emacs, The GNU Emacs Manual}).
-
-By default, Emacs (installed with Guix) ``knows'' where these packages
-are placed, so you do not need to perform any configuration. If, for
-some reason, you want to avoid auto-loading Emacs packages installed
-with Guix, you can do so by running Emacs with @code{--no-site-file}
-option (@pxref{Init File,,, emacs, The GNU Emacs Manual}).
+When you install Emacs packages with Guix, the Elisp files are placed
+under the @file{share/emacs/site-lisp/} directory of the profile in
+which they are installed. The Elisp libraries are made available to
+Emacs through the @code{EMACSLOADPATH} environment variable, which is
+set when installing Emacs itself.
+
+Additionally, autoload definitions are automatically evaluated at the
+initialization of Emacs, by the Guix-specific
+@code{guix-emacs-autoload-packages} procedure. If, for some reason, you
+want to avoid auto-loading the Emacs packages installed with Guix, you
+can do so by running Emacs with the @code{--no-site-file} option
+(@pxref{Init File,,, emacs, The GNU Emacs Manual}).
@subsection The GCC toolchain
Setting up network access is almost always a requirement because the
image does not contain all the software and tools that may be needed.
+@cindex proxy, during system installation
+If you need HTTP and HTTPS access to go through a proxy, run the
+following command:
+
+@example
+herd set-http-proxy guix-daemon @var{URL}
+@end example
+
+@noindent
+where @var{URL} is the proxy URL, for example
+@code{http://example.org:8118}.
+
@cindex installing over SSH
If you want to, you can continue the installation remotely by starting
an SSH server:
@itemx -A [@var{regexp}]
List packages currently available in the distribution for this system
(@pxref{GNU Distribution}). When @var{regexp} is specified, list only
-installed packages whose name matches @var{regexp}.
+available packages whose name matches @var{regexp}.
For each package, print the following items separated by tabs: its name,
its version string, the parts of the package (@pxref{Packages with
@end example
where @var{command} and @var{arg}@dots{} are passed unmodified to the
-@command{guix} command if the specified revision. The @var{options} that define
+@command{guix} command of the specified revision. The @var{options} that define
this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}):
@table @code
additionally includes Git and strace:
@example
-guix environment guix --ad-hoc git strace
+guix environment --pure guix --ad-hoc git strace
@end example
Sometimes it is desirable to isolate the environment as much as
It first creates the @code{@code{package}-autoloads.el} file, then it
byte compiles all Emacs Lisp files. Differently from the Emacs
packaging system, the Info documentation files are moved to the standard
-documentation directory and the @file{dir} file is deleted. Each
-package is installed in its own directory under
-@file{share/emacs/site-lisp/guix.d}.
+documentation directory and the @file{dir} file is deleted. The Elisp
+package files are installed directly under @file{share/emacs/site-lisp}.
@end defvr
@defvr {Scheme Variable} font-build-system
@dots{})} expression to construct the file name @emph{at run time}.
@end deffn
+@deffn {Scheme Syntax} with-parameters ((@var{parameter} @var{value}) @dots{}) @var{exp}
+This macro is similar to the @code{parameterize} form for
+dynamically-bound @dfn{parameters} (@pxref{Parameters,,, guile, GNU
+Guile Reference Manual}). The key difference is that it takes effect
+when the file-like object returned by @var{exp} is lowered to a
+derivation or store item.
+
+A typical use of @code{with-parameters} is to force the system in effect
+for a given object:
+
+@lisp
+(with-parameters ((%current-system "i686-linux"))
+ coreutils)
+@end lisp
+
+The example above returns an object that corresponds to the i686 build
+of Coreutils, regardless of the current value of @code{%current-system}.
+@end deffn
+
Of course, in addition to gexps embedded in ``host'' code, there are
also modules containing build tools. To make it clear that they are
When @var{packages} is omitted, @command{guix weather} checks the availability
of substitutes for @emph{all} the packages, or for those specified with
@option{--manifest}; otherwise it only considers the specified packages. It
-is also possible to query specific system types with @option{--system}. The
-available options are listed below.
+is also possible to query specific system types with @option{--system}.
+@command{guix weather} exits with a non-zero code when the fraction of
+available substitutes is below 100%.
+
+The available options are listed below.
@table @code
@item --substitute-urls=@var{urls}
with the @code{-m} option of @command{guix package} (@pxref{Invoking
guix package}).
+This option can be repeated several times, in which case the manifests
+are concatenated.
+
@item --coverage[=@var{count}]
@itemx -c [@var{count}]
Report on substitute coverage for packages: list packages with at least
If you are a Guix developer, or if you are taking care of this build farm,
you'll probably want to have a closer look at these packages: they may simply
fail to build.
+
+@item --display-missing
+Display the list of store items for which substitutes are missing.
@end table
@node Invoking guix processes
only the Linux-libre kernel is supported. In the future, it will be
possible to use the GNU@tie{}Hurd.}.
+@item @code{kernel-loadable-modules} (default: '())
+A list of objects (usually packages) to collect loadable kernel modules
+from--e.g. @code{(list ddcci-driver-linux)}.
+
@item @code{kernel-arguments} (default: @code{'("quiet")})
List of strings or gexps representing additional arguments to pass on
the command-line of the kernel---e.g., @code{("console=ttyS0")}.
;; The Catalan layout.
(keyboard-layout "es" "cat")
+;; Arabic layout with "Alt-Shift" to switch to US layout.
+(keyboard-layout "ar,us" #:options '("grp:alt_shift_toggle"))
+
;; The Latin American Spanish layout. In addition, the
;; "Caps Lock" key is used as an additional "Ctrl" key,
;; and the "Menu" key is used as a "Compose" key to enter
Return a service that sets the host name to @var{name}.
@end deffn
+@defvr {Scheme Variable} console-font-service-type
+Install the given fonts on the specified ttys (fonts are per
+virtual console on the kernel Linux). The value of this service is a list of
+tty/font pairs. The font can be the name of a font provided by the @code{kbd}
+package or any valid argument to @command{setfont}, as in this example:
+
+@lisp
+`(("tty1" . "LatGrkCyr-8x16")
+ ("tty2" . ,(file-append
+ font-tamzen
+ "/share/kbd/consolefonts/TamzenForPowerline10x20.psf"))
+ ("tty3" . ,(file-append
+ font-terminus
+ "/share/consolefonts/ter-132n"))) ; for HDPI
+@end lisp
+@end defvr
+
@deffn {Scheme Procedure} login-service @var{config}
Return a service to run login according to @var{config}, a
@code{<login-configuration>} object, which specifies the message of the day,
File where @command{guix-daemon}'s standard output and standard error
are written.
+@cindex HTTP proxy, for @code{guix-daemon}
+@cindex proxy, for @code{guix-daemon} HTTP access
@item @code{http-proxy} (default: @code{#f})
-The HTTP proxy used for downloading fixed-output derivations and
-substitutes.
+The URL of the HTTP and HTTPS proxy used for downloading fixed-output
+derivations and substitutes.
+
+It is also possible to change the daemon's proxy at run time through the
+@code{set-http-proxy} action, which restarts it:
+
+@example
+herd set-http-proxy guix-daemon http://localhost:8118
+@end example
+
+To clear the proxy settings, run:
+
+@example
+herd set-http-proxy guix-daemon
+@end example
@item @code{tmpdir} (default: @code{#f})
A directory path where the @command{guix-daemon} will perform builds.
(operating-system
;; @dots{}
- (users (cons (user-acount
+ (users (cons (user-account
;; @dots{}
(supplementary-groups
'("adbusers" ;for adb
services admin)} module provides an interface to GNU@tie{}Rot[t]log, a
log rotation tool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}).
-The example below defines an operating system that provides log rotation
-with the default settings, for commonly encountered log files.
+This service is part of @code{%base-services}, and thus enabled by
+default, with the default settings, for commonly encountered log files.
+The example below shows how to extend it with an additional
+@dfn{rotation}, should you need to do that (usually, services that
+produce log files already take care of that):
@lisp
(use-modules (guix) (gnu))
-(use-service-modules admin mcron)
-(use-package-modules base idutils)
+(use-service-modules admin)
+
+(define my-log-files
+ ;; Log files that I want to rotate.
+ '("/var/log/something.log" "/var/log/another.log"))
(operating-system
;; @dots{}
- (services (cons (service rottlog-service-type)
+ (services (cons (simple-service 'rotate-my-stuff
+ rottlog-service-type
+ (list (log-rotation
+ (frequency 'daily)
+ (files my-log-files))))
%base-services)))
@end lisp
@lisp
(service prosody-service-type
(prosody-configuration
- (modules-enabled (cons "groups" "mam" %default-modules-enabled))
+ (modules-enabled (cons* "groups" "mam" %default-modules-enabled))
(int-components
(list
(int-component-configuration
/etc/nginx/modules/ngx_http_accept_language_module.so")))
@end lisp
+@item @code{global-directives} (default: @code{'((events . ()))})
+Association list of global directives for the top level of the nginx
+configuration. Values may themselves be association lists.
+
+@lisp
+(global-directives
+ `((worker_processes . 16)
+ (pcre_jit . on)
+ (events . ((worker_connections . 1024)))))
+@end lisp
+
@item @code{extra-content} (default: @code{""})
Extra content for the @code{http} block. Should be string or a string
valued G-expression.
This is the service type for Mumi.
@end defvr
+@deftp {Data Type} mumi-configuration
+Data type representing the Mumi service configuration. This type has the
+following fields:
+
+@table @asis
+@item @code{mumi} (default: @code{mumi})
+The Mumi package to use.
+
+@item @code{mailer?} (default: @code{#true})
+Whether to enable or disable the mailer component.
+
+@item @code{mumi-configuration-sender}
+The email address used as the sender for comments.
+
+@item @code{mumi-configuration-smtp}
+A URI to configure the SMTP settings for Mailutils. This could be
+something like @code{sendmail:///path/to/bin/msmtp} or any other URI
+supported by Mailutils. @xref{SMTP Mailboxes, SMTP Mailboxes,,
+mailutils, GNU@tie{}Mailutils}.
+
+@end table
+@end deftp
+
+
@subsubheading FastCGI
@cindex fastcgi
@cindex fcgiwrap
@item @code{nfs-utils} (default: @code{nfs-utils})
The nfs-utils package to use.
-@item @code{nfs-version} (default: @code{#f})
-If a string value is provided, the @command{rpc.nfsd} daemon will be
-limited to supporting the given version of the NFS protocol.
+@item @code{nfs-versions} (default: @code{'("4.2" "4.1" "4.0")})
+If a list of string values is provided, the @command{rpc.nfsd} daemon
+will be limited to supporting the given versions of the NFS protocol.
@item @code{exports} (default: @code{'()})
This is a list of directories the NFS server should export. Each entry
@end table
@end deftp
+@cindex modprobe
+@cindex kernel module loader
+@subsubsection Kernel Module Loader Service
+
+The kernel module loader service allows one to load loadable kernel
+modules at boot. This is especially useful for modules that don't
+autoload and need to be manually loaded, as it's the case with
+@code{ddcci}.
+
+@deffn {Scheme Variable} kernel-module-loader-service-type
+The service type for loading loadable kernel modules at boot with
+@command{modprobe}. Its value must be a list of strings representing
+module names. For example loading the drivers provided by
+@code{ddcci-driver-linux}, in debugging mode by passing some module
+parameters, can be done as follow:
+
+@lisp
+(use-modules (gnu) (gnu services))
+(use-package-modules linux)
+(use-service-modules linux)
+
+(define ddcci-config
+ (plain-file "ddcci.conf"
+ "options ddcci dyndbg delay=120"))
+
+(operating-system
+ ...
+ (services (cons* (service kernel-module-loader-service-type
+ '("ddcci" "ddcci_backlight"))
+ (simple-service 'ddcci-config etc-service-type
+ (list `("modprobe.d/ddcci.conf"
+ ,ddcci-config)))
+ %base-services))
+ (kernel-loadable-modules (list ddcci-driver-linux)))
+@end lisp
+@end deffn
@node Miscellaneous Services
@subsection Miscellaneous Services
@command{guix deploy} can log in as an unprivileged user and employ
@code{sudo} to escalate privileges. This will only work if @code{sudo} is
currently installed on the remote and can be invoked non-interactively as
-@code{user}. That is: the line in @code{sudoers} granting @code{user} the
-ability to use @code{sudo} must contain the @code{NOPASSWD} tag.
+@code{user}. That is, the line in @code{sudoers} granting @code{user} the
+ability to use @code{sudo} must contain the @code{NOPASSWD} tag. This can
+be accomplished with the following operating system configuration snippet:
+
+@lisp
+(use-modules ...
+ (gnu system)) ;for %sudoers-specification
+
+(define %user "username")
+
+(operating-system
+ ...
+ (sudoers-file
+ (plain-file "sudoers"
+ (string-append (plain-file-content %sudoers-specification)
+ (format #f "~a ALL = NOPASSWD: ALL~%"
+ %user)))))
+
+@end lisp
+
+For more information regarding the format of the @file{sudoers} file,
+consult @command{man sudoers}.
@deftp {Data Type} machine
This is the data type representing a single machine in a heterogeneous Guix
HCoop / jackhill / guix / guix.git / blobdiff