diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 12 | ||||
| -rw-r--r-- | doc/guix.texi | 223 |
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 |