aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2021-11-23 11:22:30 +0100
committerLudovic Courtès <ludo@gnu.org>2021-11-23 11:29:38 +0100
commitb15e543d303ea58fdc0f0541c708389f9d513e3d (patch)
tree5c4bd48d67d4d3cd4806269dcabf58382f448bed /doc
parent4efc08d895274ee39e6e6e5c49121fb05a0281b6 (diff)
parentdaf7b5ecef8de0e536ffd8d2957f022d010767a8 (diff)
downloadguix-b15e543d303ea58fdc0f0541c708389f9d513e3d.tar
guix-b15e543d303ea58fdc0f0541c708389f9d513e3d.tar.gz
Merge branch 'master' into core-updates-frozen
Diffstat (limited to 'doc')
-rw-r--r--doc/contributing.texi12
-rw-r--r--doc/guix.texi223
2 files changed, 143 insertions, 92 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi
index db0f836157..aa6bfc2e65 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -120,12 +120,12 @@ export ACLOCAL_PATH=/usr/share/aclocal
@xref{Macro Search Path,,, automake, The GNU Automake Manual}, for
more information.
-Then, run @command{./configure} as usual. Make sure to pass
-@code{--localstatedir=@var{directory}} where @var{directory} is the
-@code{localstatedir} value used by your current installation (@pxref{The
-Store}, for information about this), usually @file{/var}. Note that you
-will probably not run @command{make install} at the end (you don't have
-to) but it's still important to pass the right @code{localstatedir}.
+Then, run @command{./configure --localstatedir=@var{directory}}, where
+@var{directory} is the @code{localstatedir} value used by your current
+installation (@pxref{The Store}, for information about this), usually
+@file{/var}. Note that you will probably not run @command{make install}
+at the end (you don't have to) but it's still important to pass the
+right @code{localstatedir}.
Finally, you have to invoke @code{make && make check} to build Guix and
run the tests (@pxref{Running the Test Suite}). If anything fails, take
diff --git a/doc/guix.texi b/doc/guix.texi
index da21fe339d..a503ed5ee0 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -30,7 +30,7 @@ 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, 2020, 2021 Leo Famulari@*
-Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020 Ricardo Wurmus@*
+Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016, 2017, 2018, 2021 Chris Marusich@*
Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Efraim Flashner@*
@@ -321,6 +321,7 @@ System Configuration
* operating-system Reference:: Detail of operating-system declarations.
* File Systems:: Configuring file system mounts.
* Mapped Devices:: Block device extra processing.
+* Swap Space:: Backing RAM with disk space.
* User Accounts:: Specifying user accounts.
* Keyboard Layout:: How the system interprets key strokes.
* Locales:: Language and cultural convention settings.
@@ -2517,10 +2518,9 @@ system relative to this path. If you have opted for @file{/boot/efi} as an
EFI mount point for example, mount it at @file{/mnt/boot/efi} now so it is
found by @code{guix system init} afterwards.
-Finally, if you plan to use one or more swap partitions (@pxref{Memory
-Concepts, swap space,, libc, The GNU C Library Reference Manual}), make
-sure to initialize them with @command{mkswap}. Assuming you have one
-swap partition on @file{/dev/sda3}, you would run:
+Finally, if you plan to use one or more swap partitions (@pxref{Swap
+Space}), make sure to initialize them with @command{mkswap}. Assuming
+you have one swap partition on @file{/dev/sda3}, you would run:
@example
mkswap /dev/sda3
@@ -11982,14 +11982,14 @@ guix import cran --archive=git https://github.com/immunogenomics/harmony
@item texlive
@cindex TeX Live
@cindex CTAN
-Import metadata from @uref{https://www.ctan.org/, CTAN}, the
-comprehensive TeX archive network for TeX packages that are part of the
-@uref{https://www.tug.org/texlive/, TeX Live distribution}.
+Import TeX package information from the TeX Live package database for
+TeX packages that are part of the @uref{https://www.tug.org/texlive/,
+TeX Live distribution}.
-Information about the package is obtained through the XML API provided
-by CTAN, while the source code is downloaded from the SVN repository of
-the Tex Live project. This is done because the CTAN does not keep
-versioned archives.
+Information about the package is obtained from the TeX Live package
+database, a plain text file that is included in the @code{texlive-bin}
+package. The source code is downloaded from possibly multiple locations
+in the SVN repository of the Tex Live project.
The command command below imports metadata for the @code{fontspec}
TeX package:
@@ -11998,19 +11998,6 @@ TeX package:
guix import texlive fontspec
@end example
-When @option{--archive=@var{directory}} is added, the source code is
-downloaded not from the @file{latex} sub-directory of the
-@file{texmf-dist/source} tree in the TeX Live SVN repository, but from
-the specified sibling @var{directory} under the same root.
-
-The command below imports metadata for the @code{ifxetex} package from
-CTAN while fetching the sources from the directory
-@file{texmf/source/generic}:
-
-@example
-guix import texlive --archive=generic ifxetex
-@end example
-
@item json
@cindex JSON, import
Import package metadata from a local JSON file. Consider the following
@@ -14206,6 +14193,7 @@ instance to support new system services.
* operating-system Reference:: Detail of operating-system declarations.
* File Systems:: Configuring file system mounts.
* Mapped Devices:: Block device extra processing.
+* Swap Space:: Backing RAM with disk space.
* User Accounts:: Specifying user accounts.
* Keyboard Layout:: How the system interprets key strokes.
* Locales:: Language and cultural convention settings.
@@ -14374,7 +14362,7 @@ configuration, but with a few modifications.
@cindex encrypted disk
The configuration for a typical ``desktop'' usage, with an encrypted
-root partition, the X11 display
+root partition, a swap file on the root partition, the X11 display
server, GNOME and Xfce (users can choose which of these desktop
environments to use at the log-in screen by pressing @kbd{F1}), network
management, power management, and more, would look like this:
@@ -14572,38 +14560,9 @@ A list of mapped devices. @xref{Mapped Devices}.
@item @code{file-systems}
A list of file systems. @xref{File Systems}.
-@cindex swap devices
-@cindex swap space
@item @code{swap-devices} (default: @code{'()})
-A list of UUIDs, file system labels, or strings identifying devices or
-files to be used for ``swap
-space'' (@pxref{Memory Concepts,,, libc, The GNU C Library Reference
-Manual}). Here are some examples:
-
-@table @code
-@item (list (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb"))
-Use the swap partition with the given UUID@. You can learn the UUID of a
-Linux swap partition by running @command{swaplabel @var{device}}, where
-@var{device} is the @file{/dev} file name of that partition.
-
-@item (list (file-system-label "swap"))
-Use the partition with label @code{swap}. Again, the
-@command{swaplabel} command allows you to view and change the label of a
-Linux swap partition.
-
-@item (list "/swapfile")
-Use the file @file{/swapfile} as swap space.
-
-@item (list "/dev/sda3" "/dev/sdb2")
-Use the @file{/dev/sda3} and @file{/dev/sdb2} partitions as swap space.
-We recommend referring to swap devices by UUIDs or labels as shown above
-instead.
-@end table
-
-It is possible to specify a swap file in a file system on a mapped
-device (under @file{/dev/mapper}), provided that the necessary device
-mapping and file system are also specified. @xref{Mapped Devices} and
-@ref{File Systems}.
+@cindex swap devices
+A list of swap spaces. @xref{Swap Space}.
@item @code{users} (default: @code{%base-user-accounts})
@itemx @code{groups} (default: @code{%base-groups})
@@ -15193,7 +15152,8 @@ It is also desirable to encrypt swap space, since swap space may contain
sensitive data. One way to accomplish that is to use a swap file in a
file system on a device mapped via LUKS encryption. In this way, the
swap file is encrypted because the entire device is encrypted.
-@xref{Preparing for Installation,,Disk Partitioning}, for an example.
+@xref{Swap Space}, or @xref{Preparing for Installation,,Disk
+Partitioning}, for an example.
A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1}
may be declared as follows:
@@ -15225,6 +15185,106 @@ Devices @file{/dev/mapper/vg0-alpha} and @file{/dev/mapper/vg0-beta} can
then be used as the @code{device} of a @code{file-system} declaration
(@pxref{File Systems}).
+@node Swap Space
+@section Swap Space
+@cindex swap space
+
+Swap space, as it is commonly called, is a disk area specifically
+designated for paging: the process in charge of memory management
+(the Linux kernel or Hurd's default pager) can decide that some memory
+pages stored in RAM which belong to a running program but are unused
+should be stored on disk instead. It unloads those from the RAM,
+freeing up precious fast memory, and writes them to the swap space. If
+the program tries to access that very page, the memory management
+process loads it back into memory for the program to use.
+
+A common misconception about swap is that it is only useful when small
+amounts of RAM are available to the system. However, it should be noted
+that kernels often use all available RAM for disk access caching to make
+I/O faster, and thus paging out unused portions of program memory will
+expand the RAM available for such caching.
+
+For a more detailed description of how memory is managed from the
+viewpoint of a monolithic kernel, @xref{Memory
+Concepts,,, libc, The GNU C Library Reference Manual}.
+
+The Linux kernel has support for swap partitions and swap files: the
+former uses a whole disk partition for paging, whereas the second uses a
+file on a file system for that (the file system driver needs to support
+it). On a comparable setup, both have the same performance, so one
+should consider ease of use when deciding between them. Partitions are
+``simpler'' and do not need file system support, but need to be
+allocated at disk formatting time (logical volumes notwithstanding),
+whereas files can be allocated and deallocated at any time.
+
+Note that swap space is not zeroed on shutdown, so sensitive data (such
+as passwords) may linger on it if it was paged out. As such, you should
+consider having your swap reside on an encrypted device (@pxref{Mapped
+Devices}).
+
+@deftp {Data Type} swap-space
+Objects of this type represent swap spaces. They contain the following
+members:
+
+@table @asis
+@item @code{target}
+The device or file to use, either a UUID, a @code{file-system-label} or
+a string, as in the definition of a @code{file-system} (@pxref{File
+Systems}).
+
+@item @code{dependencies} (default: @code{'()})
+A list of @code{file-system} or @code{mapped-device} objects, upon which
+the availability of the space depends. Note that just like for
+@code{file-system} objects, dependencies which are needed for boot and
+mounted in early userspace are not managed by the Shepherd, and so
+automatically filtered out for you.
+
+@item @code{priority} (default: @code{#f})
+Only supported by the Linux kernel. Either @code{#f} to disable swap
+priority, or an integer between 0 and 32767. The kernel will first use
+swap spaces of higher priority when paging, and use same priority spaces
+on a round-robin basis. The kernel will use swap spaces without a set
+priority after prioritized spaces, and in the order that they appeared in
+(not round-robin).
+
+@item @code{discard?} (default: @code{#f})
+Only supported by the Linux kernel. When true, the kernel will notify
+the disk controller of discarded pages, for example with the TRIM
+operation on Solid State Drives.
+
+@end table
+@end deftp
+
+Here are some examples:
+
+@lisp
+(swap-space (target (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
+@end lisp
+
+Use the swap partition with the given UUID@. You can learn the UUID of a
+Linux swap partition by running @command{swaplabel @var{device}}, where
+@var{device} is the @file{/dev} file name of that partition.
+
+@lisp
+(swap-space
+ (target (file-system-label "swap"))
+ (dependencies (list lvm-device)))
+@end lisp
+
+Use the partition with label @code{swap}, which can be found after the
+@var{lvm-device} mapped device has been opened. Again, the
+@command{swaplabel} command allows you to view and change the label of a
+Linux swap partition.
+
+@lisp
+(swap-space
+ (target "/btrfs/swapfile")
+ (dependencies (list btrfs-fs)))
+@end lisp
+
+Use the file @file{/btrfs/swapfile} as swap space, which is present on the
+@var{btrfs-fs} filesystem.
+
@node User Accounts
@section User Accounts
@@ -33469,6 +33529,17 @@ Enable or disable debug output.
@item @code{enable-iptables?} (default @code{#t})
Enable or disable the addition of iptables rules.
+@item @code{environment-variables} (default: @code{()})
+List of environment variables to set for @command{dockerd}.
+
+This must be a list of strings where each string has the form
+@samp{@var{key}=@var{value}} as in this example:
+
+@lisp
+(list "LANGUAGE=eo:ca:eu"
+ "TMPDIR=/tmp/dockerd")
+@end lisp
+
@end table
@end deftp
@@ -35337,7 +35408,7 @@ VM@. To enable that you'll also have to pass the following flags to @command{qe
@example
-device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5
-chardev spicevmc,name=vdagent,id=vdagent
--device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent,
+-device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent,\
name=com.redhat.spice.0
@end example
@@ -36161,9 +36232,8 @@ The @command{guix home import} command reads some of the ``dot files''
such as @file{~/.bashrc} found in your home directory and copies them to
the given directory, @file{~/src/guix-config} in this case; it also
reads the contents of your profile, @file{~/.guix-profile}, and, based
-on that, it outputs a Home configuration that resembles your current
-configuration. You can dump that configuration to a file and you're
-ready to go!
+on that, it populates @file{~/src/guix-config/home-configuration.scm}
+with a Home configuration that resembles your current configuration.
A simple setup can include Bash and a custom text configuration, like in
the example below. Don't be afraid to declare home environment parts,
@@ -36895,33 +36965,14 @@ $ guix home list-generations 10d
@item import
Generate a @dfn{home environment} from the packages in the default
profile and configuration files found in the user's home directory. The
-configuration files will be copied to the specified directory. Note
-that not every home service that exists is supported (@pxref{Home
-Services}).
+configuration files will be copied to the specified directory, and a
+@file{home-configuration.scm} will be populated with the home
+environment. Note that not every home service that exists is supported
+(@pxref{Home Services}).
@example
$ guix home import ~/guix-config
-;; This "home-environment" file can be passed to 'guix home reconfigure'
-;; to reproduce the content of your profile. This is "symbolic": it only
-;; specifies package names. To reproduce the exact same profile, you also
-;; need to capture the channels being used, as returned by "guix describe".
-;; See the "Replicating Guix" section in the manual.
-
-(use-modules
- (gnu home)
- (gnu packages)
- (gnu home services shells))
-
-(home-environment
- (packages
- (map specification->package
- (list "glibc-locales" "nss-certs" "nss")))
- (services
- (list (service
- home-bash-service-type
- (home-bash-configuration
- (bashrc
- (list (local-file "/home/charlie/guix-config/.bashrc"))))))))
+guix home: '/home/alice/guix-config' populated with all the Home configuration files
@end example
@end table