diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/build.scm | 11 | ||||
| -rw-r--r-- | doc/contributing.texi | 66 | ||||
| -rw-r--r-- | doc/guix-cookbook.texi | 51 | ||||
| -rw-r--r-- | doc/guix.texi | 132 |
4 files changed, 243 insertions, 17 deletions
diff --git a/doc/build.scm b/doc/build.scm index 564b0e1591..90fbf1f0e2 100644 --- a/doc/build.scm +++ b/doc/build.scm @@ -51,7 +51,16 @@ (@@ (guix self) file-append*)) (define translated-texi-manuals - (@@ (guix self) translate-texi-manuals)) + (let ((translated (@@ (guix self) translate-texi-manuals))) + (lambda (source) + (let ((result (translated source))) + ;; Build with 'guile-3.0-latest', which is linked against + ;; 'libgc/disable-munmap', to avoid the dreaded "mmap(PROT_NONE) + ;; failed" crash: <https://bugs.gnu.org/47428>. + (computed-file (computed-file-name result) + (computed-file-gexp result) + #:options (computed-file-options result) + #:guile guile-3.0-latest))))) (define info-manual (@@ (guix self) info-manual)) diff --git a/doc/contributing.texi b/doc/contributing.texi index e612ea7b23..d1b77d7d05 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -26,7 +26,7 @@ choice. * Packaging Guidelines:: Growing the distribution. * Coding Style:: Hygiene of the contributor. * Submitting Patches:: Share your work. -* Tracking Bugs and Patches:: Using Debbugs. +* Tracking Bugs and Patches:: Keeping it all organized. * Commit Access:: Pushing to the official repository. * Updating the Guix Package:: Updating the Guix package definition. * Translating Guix:: Make Guix speak your native language. @@ -1223,6 +1223,18 @@ for more information. You can install @command{git send-email} with @node Tracking Bugs and Patches @section Tracking Bugs and Patches +This section describes how the Guix project tracks its bug reports and +patch submissions. + +@menu +* The Issue Tracker:: The official bug and patch tracker. +* Debbugs User Interfaces:: Ways to interact with Debbugs. +* Debbugs Usertags:: Tag reports with custom labels. +@end menu + +@node The Issue Tracker +@subsection The Issue Tracker + @cindex bug reports, tracking @cindex patch submissions, tracking @cindex issue tracking @@ -1234,6 +1246,9 @@ email to @email{bug-guix@@gnu.org}, while patch submissions are filed against the @code{guix-patches} package by sending email to @email{guix-patches@@gnu.org} (@pxref{Submitting Patches}). +@node Debbugs User Interfaces +@subsection Debbugs User Interfaces + A web interface (actually @emph{two} web interfaces!) are available to browse issues: @@ -1271,6 +1286,55 @@ For example, to list all open issues on @code{guix-patches}, hit: @xref{Top,,, debbugs-ug, Debbugs User Guide}, for more information on this nifty tool! +@node Debbugs Usertags +@subsection Debbugs Usertags + +@cindex usertags, for debbugs +@cindex Debbugs usertags +Debbugs provides a feature called @dfn{usertags} that allows any user to +tag any bug with an arbitrary label. Bugs can be searched by usertag, +so this is a handy way to organize bugs@footnote{The list of usertags is +public information, and anyone can modify any user's list of usertags, +so keep that in mind if you choose to use this feature.}. + +For example, to view all the bug reports (or patches, in the case of +@code{guix-patches}) tagged with the usertag @code{powerpc64le-linux} +for the user @code{guix}, open a URL like the following in a web +browser: +@url{https://debbugs.gnu.org/cgi-bin/pkgreport.cgi?tag=powerpc64le-linux;users=guix}. + +For more information on how to use usertags, please refer to the +documentation for Debbugs or the documentation for whatever tool you use +to interact with Debbugs. + +In Guix, we are experimenting with usertags to keep track of +architecture-specific issues. To facilitate collaboration, all our +usertags are associated with the single user @code{guix}. The following +usertags currently exist for that user: + +@table @code + +@item powerpc64le-linux +The purpose of this usertag is to make it easy to find the issues that +matter most for the @code{powerpc64le-linux} system type. Please assign +this usertag to bugs or patches that affect @code{powerpc64le-linux} but +not other system types. In addition, you may use it to identify issues +that for some reason are particularly important for the +@code{powerpc64le-linux} system type, even if the issue affects other +system types, too. + +@item reproducibility +For issues related to reproducibility. For example, it would be +appropriate to assign this usertag to a bug report for a package that +fails to build reproducibly. + +@end table + +If you're a committer and you want to add a usertag, just start using it +with the @code{guix} user. If the usertag proves useful to you, +consider updating this section of the manual so that others will know +what your usertag means. + @node Commit Access @section Commit Access diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index ed0cd19cd5..cbec643cc6 100644 --- a/doc/guix-cookbook.texi +++ b/doc/guix-cookbook.texi @@ -17,6 +17,7 @@ Copyright @copyright{} 2020 Marcin Karpezo@* Copyright @copyright{} 2020 Brice Waegeneire@* Copyright @copyright{} 2020 André Batista@* Copyright @copyright{} 2020 Christopher Lemmer Webber +Copyright @copyright{} 2021 Joshua Branson@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -85,8 +86,8 @@ Packaging System Configuration -* Customizing the Kernel:: Creating and using a custom Linux kernel - +* Auto-Login to a Specific TTY:: Automatically Login a User to a Specific TTY +* Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System. @end detailmenu @end menu @@ -1349,6 +1350,7 @@ chapter is to demonstrate some advanced configuration concepts. reference. @menu +* Auto-Login to a Specific TTY:: Automatically Login a User to a Specific TTY * Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System. * Guix System Image API:: Customizing images to target specific platforms. * Connecting to Wireguard VPN:: Connecting to a Wireguard VPN. @@ -1359,6 +1361,51 @@ reference. * Setting up NGINX with Lua:: Configuring NGINX web-server to load Lua modules. @end menu +@node Auto-Login to a Specific TTY +@section Auto-Login to a Specific TTY + +While the Guix manual explains auto-login one user to @emph{all} TTYs ( +@pxref{auto-login to TTY,,, guix, GNU Guix Reference Manual}), some +might prefer a situation, in which one user is logged into one TTY with +the other TTYs either configured to login different users or no one at +all. Note that one can auto-login one user to any TTY, but it is +usually advisable to avoid @code{tty1}, which, by default, is used to +log warnings and errors. + +Here is how one might set up auto login for one user to one tty: + +@lisp +(define (auto-login-to-tty config tty user) + (if (string=? tty (mingetty-configuration-tty config)) + (mingetty-configuration + (inherit config) + (auto-login user)) + config)) + +(define %my-services + (modify-services %base-services + ;; @dots{} + (mingetty-service-type config => + (auto-login-to-tty + config "tty3" "alice")))) + +(operating-system + ;; @dots{} + (services %my-services)) +@end lisp + +One could also @code{compose} (@pxref{Higher-Order Functions,,, guile, +The Guile Reference Manual}) @code{auto-login-to-tty} to login multiple +users to multiple ttys. + +Finally, here is a note of caution. Setting up auto login to a TTY, +means that anyone can turn on your computer and run commands as your +regular user. +However, if you have an encrypted root partition, and thus already need +to enter a passphrase when the system boots, auto-login might be a +convenient option. + + @node Customizing the Kernel @section Customizing the Kernel diff --git a/doc/guix.texi b/doc/guix.texi index c0d456c8ea..ff3c81c657 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -91,6 +91,9 @@ Copyright @copyright{} 2020 Edgar Vincent@* Copyright @copyright{} 2021 Maxime Devos@* Copyright @copyright{} 2021 B. Wilson@* Copyright @copyright{} 2021 Xinglu Chen@* +Copyright @copyright{} 2021 Raghav Gururajan@* +Copyright @copyright{} 2021 Domagoj Stolfa@* +Copyright @copyright{} 2021 Hui Lu@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -2541,7 +2544,7 @@ provide the declaration of the operating system to be installed. To that end, the installation system comes with three text editors. We recommend GNU nano (@pxref{Top,,, nano, GNU nano Manual}), which supports syntax highlighting and parentheses matching; other editors -include GNU Zile (an Emacs clone), and +include mg (an Emacs clone), and nvi (a clone of the original BSD @command{vi} editor). We strongly recommend storing that file on the target root file system, say, as @file{/mnt/etc/config.scm}. Failing to do that, you will have lost your @@ -6042,6 +6045,35 @@ If you forget the @code{bash} (or similar) package, @command{singularity run} and @command{singularity exec} will fail with an unhelpful ``no such file or directory'' message. @end quotation + +@item deb +This produces a Debian archive (a package with the @samp{.deb} file +extension) containing all the specified binaries and symbolic links, +that can be installed on top of any dpkg-based GNU(/Linux) distribution. +Advanced options can be revealed via the @option{--help-deb-format} +option. They allow embedding control files for more fine-grained +control, such as activating specific triggers or providing a maintainer +configure script to run arbitrary setup code upon installation. + +@example +guix pack -f deb -C xz -S /usr/bin/hello=bin/hello hello +@end example + +@quotation Note +Because archives produced with @command{guix pack} contain a collection +of store items and because each @command{dpkg} package must not have +conflicting files, in practice that means you likely won't be able to +install more than one such archive on a given system. +@end quotation + +@quotation Warning +@command{dpkg} will assume ownership of any files contained in the pack +that it does @emph{not} know about. It is unwise to install +Guix-produced @samp{.deb} files on a system where @file{/gnu/store} is +shared by other software, such as a Guix installation or other, non-deb +packs. +@end quotation + @end table @cindex relocatable binaries @@ -7423,7 +7455,7 @@ the @code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well as executables) previously installed by the @code{install} phase. This validation step consists in making sure that all the shared -libraries needed by an ELF binaries, which are listed as +libraries needed by an ELF binary, which are listed as @code{DT_NEEDED} entries in its @code{PT_DYNAMIC} segment, appear in the @code{DT_RUNPATH} entry of that binary. In other words, it ensures that running or using those binaries will not result in a ``file not found'' @@ -10141,6 +10173,16 @@ corresponding to @var{obj} for @var{system}, cross-compiling for has an associated gexp compiler, such as a @code{<package>}. @end deffn +@deffn {Procedure} gexp->approximate-sexp @var{gexp} +Sometimes, it may be useful to convert a G-exp into a S-exp. For +example, some linters (@pxref{Invoking guix lint}) peek into the build +phases of a package to detect potential problems. This conversion can +be achieved with this procedure. However, some information can be lost +in the process. More specifically, lowerable objects will be silently +replaced with some arbitrary object -- currently the list +@code{(*approximate*)}, but this may change. +@end deffn + @node Invoking guix repl @section Invoking @command{guix repl} @@ -10297,7 +10339,7 @@ Similarly, the following command builds all the available packages: @example guix build --quiet --keep-going \ - $(guix package -A | cut -f1,2 --output-delimiter=@@) + $(guix package -A | awk '@{ print $1 "@@" $2 @}') @end example @var{package-or-derivation} may be either the name of a package found in @@ -13654,7 +13696,7 @@ environment variable---in addition to the per-user profiles (@pxref{Invoking guix package}). The @code{%base-packages} variable provides all the tools one would expect for basic user and administrator tasks---including the GNU Core Utilities, the GNU Networking Utilities, -the GNU Zile lightweight text editor, @command{find}, @command{grep}, +the @command{mg} lightweight text editor, @command{find}, @command{grep}, etc. The example above adds GNU@tie{}Screen to those, taken from the @code{(gnu packages screen)} module (@pxref{Package Modules}). The @@ -13711,10 +13753,11 @@ Occasionally, instead of using the base services as is, you will want to customize them. To do this, use @code{modify-services} (@pxref{Service Reference, @code{modify-services}}) to modify the list. -For example, suppose you want to modify @code{guix-daemon} and Mingetty -(the console log-in) in the @code{%base-services} list (@pxref{Base -Services, @code{%base-services}}). To do that, you can write the -following in your operating system declaration: +@anchor{auto-login to TTY} For example, suppose you want to modify +@code{guix-daemon} and Mingetty (the console log-in) in the +@code{%base-services} list (@pxref{Base Services, +@code{%base-services}}). To do that, you can write the following in +your operating system declaration: @lisp (define %my-services @@ -13740,7 +13783,9 @@ following in your operating system declaration: This changes the configuration---i.e., the service parameters---of the @code{guix-service-type} instance, and that of all the -@code{mingetty-service-type} instances in the @code{%base-services} list. +@code{mingetty-service-type} instances in the @code{%base-services} list +(@pxref{Auto-Login to a Specific TTY, see the cookbook for how to +auto-login one user to a specific TTY,, guix-cookbook, GNU Guix Cookbook})). Observe how this is accomplished: first, we arrange for the original configuration to be bound to the identifier @code{config} in the @var{body}, and then we write the @var{body} so that it evaluates to the @@ -15483,6 +15528,14 @@ Font engine used in Kmscon. @item @code{font-size} (default: @code{12}) Font size used in Kmscon. +@item @code{keyboard-layout} (default: @code{#f}) +If this is @code{#f}, Kmscon uses the default keyboard layout---usually US +English (``qwerty'') for a 105-key PC keyboard. + +Otherwise this must be a @code{keyboard-layout} object specifying the +keyboard layout. @xref{Keyboard Layout}, for more information on how to +specify the keyboard layout. + @item @code{kmscon} (default: @var{kmscon}) The Kmscon package to use. @@ -26143,6 +26196,14 @@ the documentation at @url{https://certbot.eff.org/docs/using.html#hooks}), and gives Let's Encrypt permission to log the public IP address of the requesting machine. +@item @code{csr} (default: @code{#f}) +File name of Certificate Signing Request (CSR) in DER or PEM format. +If @code{#f} is specified, this argument will not be passed to certbot. +If a value is specified, certbot will use it to obtain a certificate, instead of +using a self-generated CSR. +The domain-name(s) mentioned in @code{domains}, must be consistent with the +domain-name(s) mentioned in CSR file. + @item @code{authentication-hook} (default: @code{#f}) Command to be run in a shell once for each certificate challenge to be answered. For this command, the shell variable @code{$CERTBOT_DOMAIN} @@ -26928,6 +26989,15 @@ Defaults to @samp{()}. The @code{(gnu services vpn)} module provides services related to @dfn{virtual private networks} (VPNs). +@subsubheading Bitmask + +@defvr {Scheme Variable} bitmask-service-type +A service type for the @uref{https://bitmask.net, Bitmask} VPN client. It makes +the client available in the system and loads its polkit policy. Please note that +the client expects an active polkit-agent, which is either run by your +desktop-environment or should be run manually. +@end defvr + @subsubheading OpenVPN It provides a @emph{client} service for your machine to connect to a @@ -27307,9 +27377,45 @@ Defaults to @samp{#f}. @end deftypevr - @c %end of automatic openvpn-server documentation +@subheading strongSwan + +Currently, the strongSwan service only provides legacy-style configuration with +@file{ipsec.conf} and @file{ipsec.secrets} files. + +@defvr {Scheme Variable} strongswan-service-type +A service type for configuring strongSwan for IPsec @acronym{VPN, +Virtual Private Networking}. Its value must be a +@code{strongswan-configuration} record as in this example: + +@lisp +(service strongswan-service-type + (strongswan-configuration + (ipsec-conf "/etc/ipsec.conf") + (ipsec-secrets "/etc/ipsec.secrets"))) +@end lisp + +@end defvr + +@deftp {Data Type} strongswan-configuration +Data type representing the configuration of the StrongSwan service. + +@table @asis +@item @code{strongswan} +The strongSwan package to use for this service. + +@item @code{ipsec-conf} (default: @code{#f}) +The file name of your @file{ipsec.conf}. If not @code{#f}, then this and +@code{ipsec-secrets} must both be strings. + +@item @code{ipsec-secrets} (default @code{#f}) +The file name of your @file{ipsec.secrets}. If not @code{#f}, then this and +@code{ipsec-conf} must both be strings. + +@end table +@end deftp + @subsubheading Wireguard @defvr {Scheme Variable} wireguard-service-type @@ -32265,10 +32371,10 @@ This is the data type representing the configuration of Docker and Containerd. @table @asis -@item @code{package} (default: @code{docker}) +@item @code{docker} (default: @code{docker}) The Docker daemon package to use. -@item @code{package} (default: @code{docker-cli}) +@item @code{docker-cli} (default: @code{docker-cli}) The Docker client package to use. @item @code{containerd} (default: @var{containerd}) @@ -32886,7 +32992,7 @@ program. That gives a lot of flexibility. The program to run in that initrd. @deffn {Scheme Procedure} expression->initrd @var{exp} @ - [#:guile %guile-3.0-static-stripped] [#:name "guile-initrd"] + [#:guile %guile-static-stripped] [#:name "guile-initrd"] Return as a file-like object a Linux initrd (a gzipped cpio archive) containing @var{guile} and that evaluates @var{exp}, a G-expression, upon booting. All the derivations referenced by @var{exp} are |