diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 169 |
1 files changed, 99 insertions, 70 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 7ffb0d738c..ea603ab56a 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -22,7 +22,7 @@ @set SUBSTITUTE-URLS https://@value{SUBSTITUTE-SERVER-1} https://@value{SUBSTITUTE-SERVER-2} @copying -Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ludovic Courtès@* +Copyright @copyright{} 2012-2022 Ludovic Courtès@* Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@* Copyright @copyright{} 2013 Nikita Karetnikov@* Copyright @copyright{} 2014, 2015, 2016 Alex Kost@* @@ -33,7 +33,7 @@ Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021 Leo Famulari@* 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@* +Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021, 2022 Efraim Flashner@* Copyright @copyright{} 2016 John Darrington@* Copyright @copyright{} 2016, 2017 Nikita Gillmann@* Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Jan Nieuwenhuizen@* @@ -564,6 +564,15 @@ build (@pxref{Tracking Bugs and Patches}). That said, the Guix community is actively working on improving this support, and now is a great time to try it and get involved! +@item riscv64-linux +little-endian 64-bit RISC-V processors, specifically RV64GC, and +Linux-Libre kernel. This playform is available as a "technology preview": +although it is supported, substitutes are not yet available from the +build farm (@pxref{Substitutes}), and some packages may fail to build +(@pxref{Tracking Bugs and Patches}). That said, the Guix community is +actively working on improving this support, and now is a great time to +try it and get involved! + @end table With Guix@tie{}System, you @emph{declare} all aspects of the operating system @@ -575,7 +584,8 @@ Manual}), the well-known GNU utilities and tool chain, as well as the graphical environment or system services of your choice. Guix System is available on all the above platforms except -@code{mips64el-linux} and @code{powerpc64le-linux}. +@code{mips64el-linux}, @code{powerpc-linux}, @code{powerpc64le-linux} and +@code{riscv64-linux}. @noindent For information on porting to other architectures or kernels, @@ -1168,6 +1178,11 @@ user @file{nobody}; a writable @file{/tmp} directory. @end itemize +The chroot does not contain a @file{/home} directory, and the @env{HOME} +environment variable is set to the non-existent +@file{/homeless-shelter}. This helps to highlight inappropriate uses of +@env{HOME} in the build scripts of packages. + You can influence the directory where the daemon stores build trees @i{via} the @env{TMPDIR} environment variable. However, the build tree within the chroot is always called @file{/tmp/guix-build-@var{name}.drv-0}, @@ -5806,17 +5821,6 @@ This is similar to the same-named option in @command{guix package} (@pxref{profile-manifest, @option{--manifest}}) and uses the same manifest files. -@item --rebuild-cache -When using @option{--manifest}, @option{--file}, or when invoked without -arguments, @command{guix shell} caches the environment so that -subsequent uses are instantaneous. The cache is invalidated anytime the -file is modified. - -The @option{--rebuild-cache} forces the cached environment to be -refreshed even if the file has not changed. This is useful if the -@command{guix.scm} or @command{manifest.scm} has external dependencies, -or if its behavior depends, say, on environment variables. - @item --pure Unset existing environment variables when building the new environment, except those specified with @option{--preserve} (see below). This has the effect of @@ -5932,6 +5936,21 @@ directory: guix shell --container --expose=$HOME=/exchange guile -- guile @end example +@item --rebuild-cache +@cindex caching, of profiles +@cindex caching, in @command{guix shell} +In most cases, @command{guix shell} caches the environment so that +subsequent uses are instantaneous. Least-recently used cache entries +are periodically removed. The cache is also invalidated, when using +@option{--file} or @option{--manifest}, anytime the corresponding file +is modified. + +The @option{--rebuild-cache} forces the cached environment to be +refreshed. This is useful when using @option{--file} or +@option{--manifest} and the @command{guix.scm} or @command{manifest.scm} +file has external dependencies, or if its behavior depends, say, on +environment variables. + @item --root=@var{file} @itemx -r @var{file} @cindex persistent environment @@ -5942,11 +5961,20 @@ register it as a garbage collector root. This is useful if you want to protect your environment from garbage collection, to make it ``persistent''. -When this option is omitted, the environment is protected from garbage -collection only for the duration of the @command{guix shell} -session. This means that next time you recreate the same environment, -you could have to rebuild or re-download packages. @xref{Invoking guix -gc}, for more on GC roots. +When this option is omitted, @command{guix shell} caches profiles so +that subsequent uses of the same environment are instantaneous---this is +comparable to using @option{--root} except that @command{guix shell} +takes care of periodically removing the least-recently used garbage +collector roots. + +In some cases, @command{guix shell} does not cache profiles---e.g., if +transformation options such as @option{--with-latest} are used. In +those cases, the environment is protected from garbage collection only +for the duration of the @command{guix shell} session. This means that +next time you recreate the same environment, you could have to rebuild +or re-download packages. + +@xref{Invoking guix gc}, for more on GC roots. @end table @command{guix shell} also supports all of the common build options that @@ -11827,11 +11855,12 @@ in the definitions of packages. @item --recursive @itemx -r -This option is deprecated in favor of @option{--serializer}. It is a -legacy alias for that with @var{type} set to @code{nar}. +The @option{--recursive} option is deprecated in favor of +@option{--serializer=nar} (see below); @option{-r} remains accepted as a +convenient shorthand. @item --serializer=@var{type} -@itemx -S +@itemx -S @var{type} Compute the hash on @var{file} using @var{type} serialization. @var{type} may be one of the following: @@ -12785,7 +12814,7 @@ otherwise. The @command{guix style} command helps packagers style their package definitions according to the latest fashionable trends. The command -currently provides the providing styling rules: +currently provides the following styling rules: @itemize @item @@ -14493,7 +14522,7 @@ your operating system declaration: (mingetty-service-type config => (mingetty-configuration (inherit config) - ;; Automatially log in as "guest". + ;; Automatically log in as "guest". (auto-login "guest"))))) (operating-system @@ -23835,9 +23864,9 @@ service found under @file{/var/lib/jami} are recreated every time the service starts. Jami accounts and their corresponding backup archives can be generated -using either the @code{jami-qt} or @code{jami-gnome} Jami clients. The -accounts should not be password-protected, but it is wise to ensure -their files are only readable by @samp{root}. +using the @code{jami} or @code{jami-gnome} Jami clients. The accounts +should not be password-protected, but it is wise to ensure their files +are only readable by @samp{root}. The next example shows how to declare that only some contacts should be allowed to communicate with a given account: @@ -23952,7 +23981,7 @@ The complete set of available configuration options is detailed below. Available @code{jami-configuration} fields are: @table @asis -@item @code{jamid} (default: @code{libring}) (type: package) +@item @code{jamid} (default: @code{libjami}) (type: package) The Jami daemon package to use. @item @code{dbus} (default: @code{dbus}) (type: package) @@ -34122,21 +34151,23 @@ Configuration System}). For instance, the @command{mount.nfs} program, which is part of the nfs-utils package, with a setuid root can be designated like this: -@example +@lisp (setuid-program (program (file-append nfs-utils "/sbin/mount.nfs"))) -@end example +@end lisp And then, to make @command{mount.nfs} setuid on your system, add the previous example to your operating system declaration by appending it to @code{%setuid-programs} like this: -@example -(setuid-programs - (append (list (setuid-program - (program (file-append nfs-utils "/sbin/mount.nfs")))) - %setuid-programs)) -@end example +@lisp +(operating-system + ;; Some fields omitted... + (setuid-programs + (append (list (setuid-program + (program (file-append nfs-utils "/sbin/mount.nfs"))) + %setuid-programs)))) +@end lisp @deftp {Data Type} setuid-program This data type represents a program with a setuid or setgid bit set. @@ -35136,6 +35167,11 @@ $ $(guix system vm my-config.scm) -m 1024 -smp 2 -nic user,model=virtio-net-pci The VM shares its store with the host system. +By default, the root file system of the VM is mounted volatile; the +@option{--persistent} option can be provided to make it persistent +instead. In that case, the VM disk-image file will be copied from the +store to the @env{TMPDIR} directory to make it writable. + Additional file systems can be shared between the host and the VM using the @option{--share} and @option{--expose} command-line options: the former specifies a directory to be shared with write access, while the latter @@ -35173,8 +35209,8 @@ QEMU monitor and the VM. @cindex Creating system images in various formats @item image @cindex image, creating disk images -The @code{image} command can produce various image types. The -image type can be selected using the @option{--image-type} option. It +The @code{image} command can produce various image types. The image +type can be selected using the @option{--image-type} option. It defaults to @code{efi-raw}. When its value is @code{iso9660}, the @option{--label} option can be used to specify a volume ID with @code{image}. By default, the root file system of a disk image is @@ -35646,6 +35682,16 @@ returned by @command{guix describe}) to determine whether commits currently in use are descendants of those deployed. When this is not the case and @code{allow-downgrades?} is false, it raises an error. This ensures you do not accidentally downgrade remote machines. + +@item @code{safety-checks?} (default: @code{#t}) +Whether to perform ``safety checks'' before deployment. This includes +verifying that devices and file systems referred to in the operating +system configuration actually exist on the target machine, and making +sure that Linux modules required to access storage devices at boot time +are listed in the @code{initrd-modules} field of the operating system. + +These safety checks ensure that you do not inadvertently deploy a system +that would fail to boot. Be careful before turning them off! @end table @end deftp @@ -37119,7 +37165,7 @@ Service}; declare daemons by extending @ref{Shepherd Home Service}; add commands, which will be invoked on by the Bash by extending @ref{Shells Home Services, @code{home-bash-service-type}}. -A good way to discover avaliable home services is using the +A good way to discover available home services is using the @command{guix home search} command (@pxref{Invoking guix home}). After the required home services are found, include its module with the @code{use-modules} form (@pxref{use-modules,, Using Guile Modules, @@ -37207,7 +37253,7 @@ The service of this type will be instantiated by every home environment automatically, there is no need to define it, but you may want to extend it with a list of packages if you want to install additional packages into your profile. Other services, which need to make some programs -avaliable to the user will also extend this service type. +available to the user will also extend this service type. The extension value is just a list of packages: @@ -37289,8 +37335,8 @@ Available @code{home-shell-profile-configuration} fields are: @code{home-environment}, DO NOT create this service manually, it can only be extended. @code{profile} is a list of file-like objects, which will go to @file{~/.profile}. By default @file{~/.profile} contains the -initialization code, which have to be evaluated by login shell to make -home-environment's profile avaliable to the user, but other commands can +initialization code which must be evaluated by the login shell to make +home-environment's profile available to the user, but other commands can be added to the file if it is really necessary. In most cases shell's configuration files are preferred places for user's customizations. Extend home-shell-profile service only if you really know what you do. @@ -37545,45 +37591,28 @@ regular expressions, sorted by relevance: @example $ guix home search shell name: home-shell-profile -location: gnu/home/services/shells.scm:73:2 +location: gnu/home/services/shells.scm:100:2 extends: home-files -description: Create `~/.profile', which is used for environment initialization -+ of POSIX compatible login shells. Can be extended with a list of strings or -+ gexps. +description: Create `~/.profile', which is used for environment initialization of POSIX compliant login shells. ++ This service type can be extended with a list of file-like objects. relevance: 6 -name: home-zsh-plugin-manager -location: gnu/home/services/shellutils.scm:28:2 -extends: home-zsh home-profile -description: Install plugins in profile and configure Zsh to load them. -relevance: 1 - -name: home-zsh-direnv -location: gnu/home/services/shellutils.scm:69:2 -extends: home-profile home-zsh -description: Enables `direnv' for `zsh'. Adds hook to `.zshrc' and installs a -+ package in the profile. -relevance: 1 - -name: home-zsh-autosuggestions -location: gnu/home/services/shellutils.scm:43:2 -extends: home-zsh-plugin-manager home-zsh -description: Enables Fish-like fast/unobtrusive autosuggestions for `zsh' and -+ sets reasonable default values for some plugin's variables to improve perfomance -+ and adjust behavior: `(history completion)' is set for strategy, manual rebind -+ and async are enabled. -relevance: 1 +name: home-fish +location: gnu/home/services/shells.scm:640:2 +extends: home-files home-profile +description: Install and configure Fish, the friendly interactive shell. +relevance: 3 name: home-zsh -location: gnu/home/services/shells.scm:236:2 +location: gnu/home/services/shells.scm:290:2 extends: home-files home-profile description: Install and configure Zsh. relevance: 1 name: home-bash -location: gnu/home/services/shells.scm:388:2 +location: gnu/home/services/shells.scm:508:2 extends: home-files home-profile -description: Install and configure Bash. +description: Install and configure GNU Bash. relevance: 1 @dots{} |