diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 111 | ||||
| -rw-r--r-- | doc/guix-cookbook.texi | 295 | ||||
| -rw-r--r-- | doc/guix.texi | 210 | ||||
| -rw-r--r-- | doc/local.mk | 2 |
4 files changed, 518 insertions, 100 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 69f0327afb..a0da871f1a 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -300,15 +300,10 @@ Geiser allows for interactive and incremental development from within Emacs: code compilation and evaluation from within buffers, access to on-line documentation (docstrings), context-sensitive completion, @kbd{M-.} to jump to an object definition, a REPL to try out your code, -and more (@pxref{Introduction,,, geiser, Geiser User Manual}). For -convenient Guix development, make sure to augment Guile’s load path so -that it finds source files from your checkout: - -@lisp -;; @r{Assuming the Guix checkout is in ~/src/guix.} -(with-eval-after-load 'geiser-guile - (add-to-list 'geiser-guile-load-path "~/src/guix")) -@end lisp +and more (@pxref{Introduction,,, geiser, Geiser User Manual}). If you +allow Emacs to load the @file{.dir-locals.el} file at the root of the +project checkout, it will cause Geiser to automatically add the local +Guix sources to the Guile load path. To actually edit the code, Emacs already has a neat Scheme mode. But in addition to that, you must not miss @@ -1345,6 +1340,12 @@ should not be delayed. When a bug is resolved, please close the thread by sending an email to @email{@var{ISSUE_NUMBER}-done@@debbugs.gnu.org}. +@menu +* Configuring Git:: +* Sending a Patch Series:: +* Teams:: +@end menu + @node Configuring Git @subsection Configuring Git @cindex git configuration @@ -1542,10 +1543,10 @@ This section describes how the Guix project tracks its bug reports, patch submissions and topic branches. @menu -* The Issue Tracker:: The official bug and patch tracker. -* Managing Patches and Branches:: How changes to Guix are managed. -* Debbugs User Interfaces:: Ways to interact with Debbugs. -* Debbugs Usertags:: Tag reports with custom labels. +* The Issue Tracker:: The official bug and patch tracker. +* Managing Patches and Branches:: How changes to Guix are managed. +* Debbugs User Interfaces:: Ways to interact with Debbugs. +* Debbugs Usertags:: Tag reports with custom labels. @end menu @node The Issue Tracker @@ -1625,6 +1626,8 @@ information on some builds and substitute availability. @node Debbugs User Interfaces @subsection Debbugs User Interfaces +@subsubsection Web interface + A web interface (actually @emph{two} web interfaces!) are available to browse issues: @@ -1646,6 +1649,88 @@ To view discussions related to issue number @var{n}, go to @indicateurl{https://issues.guix.gnu.org/@var{n}} or @indicateurl{https://bugs.gnu.org/@var{n}}. +@subsubsection Command-line interface + +Mumi also comes with a command-line interface that can be used to search +existing issues, open new issues and send patches. You do not need to +use Emacs to use the mumi command-line client. You interact with it +only on the command-line. + +To use the mumi command-line interface, navigate to a local clone of the +Guix git repository, and drop into a shell with mumi, git and +git:send-email installed. + +@example +$ cd guix +~/guix$ guix shell mumi git git:send-email +@end example + +To search for issues, say all open issues about "zig", run + +@example +~/guix [env]$ mumi search zig is:open + +#60889 Add zig-build-system +opened on 17 Jan 17:37 Z by Ekaitz Zarraga +#61036 [PATCH 0/3] Update zig to 0.10.1 +opened on 24 Jan 09:42 Z by Efraim Flashner +#39136 [PATCH] gnu: services: Add endlessh. +opened on 14 Jan 2020 21:21 by Nicol? Balzarotti +#60424 [PATCH] gnu: Add python-online-judge-tools +opened on 30 Dec 2022 07:03 by gemmaro +#45601 [PATCH 0/6] vlang 0.2 update +opened on 1 Jan 2021 19:23 by Ryan Prior +@end example + +Pick an issue and make it the "current" issue. + +@example +~/guix [env]$ mumi current 61036 + +#61036 [PATCH 0/3] Update zig to 0.10.1 +opened on 24 Jan 09:42 Z by Efraim Flashner +@end example + +Once an issue is the current issue, you can easily create and send +patches to it using + +@example +~/guix [env]$ git format-patch origin/master +~/guix [env]$ mumi send-email foo.patch bar.patch +@end example + +Note that you do not have to pass in @samp{--to} or @samp{--cc} +arguments to @command{git format-patch}. @command{mumi send-email} will +put them in correctly when sending the patches. + +To open a new issue, run + +@example +~/guix [env]$ mumi new +@end example + +and send patches + +@example +~/guix [env]$ mumi send-email foo.patch bar.patch +@end example + +@command{mumi send-email} is really a wrapper around @command{git +send-email} that automates away all the nitty-gritty of sending patches. +It uses the current issue state to automatically figure out the correct +@samp{To} address to send to, other participants to @samp{Cc}, headers +to add, etc. + +Also note that, unlike @command{git send-email}, @command{mumi +send-email} works perfectly well with single and multiple patches alike. +It automates away the debbugs dance of sending the first patch, waiting +for a response from debbugs and sending the remaining patches. It does +so by sending the first patch, polling the server for a response, and +then sending the remaining patches. This polling can unfortunately take +a few minutes. So, please be patient. + +@subsubsection Emacs interface + If you use Emacs, you may find it more convenient to interact with issues using @file{debbugs.el}, which you can install with: diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index e90d611171..91f08bfcd6 100644 --- a/doc/guix-cookbook.texi +++ b/doc/guix-cookbook.texi @@ -23,6 +23,7 @@ Copyright @copyright{} 2020 Christine Lemmer-Webber@* Copyright @copyright{} 2021 Joshua Branson@* Copyright @copyright{} 2022, 2023 Maxim Cournoyer@* Copyright @copyright{} 2023 Ludovic Courtès +Copyright @copyright{} 2023 Thomas Ieong Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -128,6 +129,7 @@ System Configuration * Connecting to Wireguard VPN:: Connecting to a Wireguard VPN. * Customizing a Window Manager:: Handle customization of a Window manager on Guix System. * Running Guix on a Linode Server:: Running Guix on a Linode Server. +* Running Guix on a Kimsufi Server:: Running Guix on a Kimsufi Server. * Setting up a bind mount:: Setting up a bind mount in the file-systems definition. * Getting substitutes from Tor:: Configuring Guix daemon to get substitutes through Tor. * Setting up NGINX with Lua:: Configuring NGINX web-server to load Lua modules. @@ -1575,6 +1577,7 @@ reference. * Connecting to Wireguard VPN:: Connecting to a Wireguard VPN. * Customizing a Window Manager:: Handle customization of a Window manager on Guix System. * Running Guix on a Linode Server:: Running Guix on a Linode Server. +* Running Guix on a Kimsufi Server:: Running Guix on a Kimsufi Server. * Setting up a bind mount:: Setting up a bind mount in the file-systems definition. * Getting substitutes from Tor:: Configuring Guix daemon to get substitutes through Tor. * Setting up NGINX with Lua:: Configuring NGINX web-server to load Lua modules. @@ -2158,6 +2161,51 @@ the @code{yubikey-manager-qt} package and either wholly disable the @samp{Applications -> OTP} view, delete the slot 1 configuration, which comes pre-configured with the Yubico OTP application. +@subsection Requiring a Yubikey to open a KeePassXC database +@cindex yubikey, keepassxc integration +The KeePassXC password manager application has support for Yubikeys, but +it requires installing a udev rules for your Guix System and some +configuration of the Yubico OTP application on the key. + +The necessary udev rules file comes from the +@code{yubikey-personalization} package, and can be installed like: + +@lisp +(use-package-modules ... security-token ...) +... +(operating-system + ... + (services + (cons* + ... + (udev-rules-service 'yubikey yubikey-personalization)))) +@end lisp + +After reconfiguring your system (and reconnecting your Yubikey), you'll +then want to configure the OTP challenge/response application of your +Yubikey on its slot 2, which is what KeePassXC uses. It's easy to do so +via the Yubikey Manager graphical configuration tool, which can be +invoked with: + +@example +guix shell yubikey-manager-qt -- ykman-gui +@end example + +First, ensure @samp{OTP} is enabled under the @samp{Interfaces} tab, +then navigate to @samp{Applications -> OTP}, and click the +@samp{Configure} button under the @samp{Long Touch (Slot 2)} section. +Select @samp{Challenge-response}, input or generate a secret key, and +click the @samp{Finish} button. If you have a second Yubikey you'd like +to use as a backup, you should configure it the same way, using the +@emph{same} secret key. + +Your Yubikey should now be detected by KeePassXC. It can be added to a +database by navigating to KeePassXC's @samp{Database -> Database +Security...} menu, then clicking the @samp{Add additional +protection...} button, then @samp{Add Challenge-Response}, selecting the +security key from the drop-down menu and clicking the @samp{OK} button +to complete the setup. + @node Dynamic DNS mcron job @section Dynamic DNS mcron job @@ -2634,6 +2682,253 @@ have an easy time spinning up new Guix images! You may need to down-size the Guix image to 6144MB, to save it as an image. Then you can resize it again to the max size. +@node Running Guix on a Kimsufi Server +@section Running Guix on a Kimsufi Server +@cindex kimsufi, Kimsufi, OVH + +To run Guix on a server hosted by @uref{https://www.kimsufi.com/, +Kimsufi}, click on the netboot tab then select rescue64-pro and restart. + +OVH will email you the credentials required to ssh into a Debian system. + +Now you can run the "install guix from @pxref{Binary Installation,,, +guix, GNU Guix}" steps: + +@example +wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh +chmod +x guix-install.sh +./guix-install.sh +guix pull +@end example + +Partition the drives and format them, first stop the raid array: + +@example +mdadm --stop /dev/md127 +mdadm --zero-superblock /dev/sda2 /dev/sdb2 +@end example + +Then wipe the disks and set up the partitions, we will create +a RAID 1 array. + +@example +wipefs -a /dev/sda +wipefs -a /dev/sdb + +parted /dev/sda --align=opt -s -m -- mklabel gpt +parted /dev/sda --align=opt -s -m -- \ + mkpart bios_grub 1049kb 512MiB \ + set 1 bios_grub on +parted /dev/sda --align=opt -s -m -- \ + mkpart primary 512MiB -512MiB + set 2 raid on +parted /dev/sda --align=opt -s -m -- mkpart primary linux-swap 512MiB 100% + +parted /dev/sdb --align=opt -s -m -- mklabel gpt +parted /dev/sdb --align=opt -s -m -- \ + mkpart bios_grub 1049kb 512MiB \ + set 1 bios_grub on +parted /dev/sdb --align=opt -s -m -- \ + mkpart primary 512MiB -512MiB \ + set 2 raid on +parted /dev/sdb --align=opt -s -m -- mkpart primary linux-swap 512MiB 100% +@end example + +Create the array: + +@example +mdadm --create /dev/md127 --level=1 --raid-disks=2 \ + --metadata=0.90 /dev/sda2 /dev/sdb2 +@end example + +Now create file systems on the relevant partitions, first the boot +partitions: + +@example +mkfs.ext4 /dev/sda1 +mkfs.ext4 /dev/sdb1 +@end example + +Then the root partition: + +@example +mkfs.ext4 /dev/md127 +@end example + +Initialize the swap partitions: + +@example +mkswap /dev/sda3 +swapon /dev/sda3 +mkswap /dev/sdb3 +swapon /dev/sdb3 +@end example + +Mount the guix drive: + +@example +mkdir /mnt/guix +mount /dev/md127 /mnt/guix +@end example + +Now is time to write an operating system declaration @file{os.scm} file; +here is a sample: + +@lisp +(use-modules (gnu) (guix)) +(use-service-modules networking ssh vpn virtualization sysctl admin mcron) +(use-package-modules ssh certs tls tmux vpn virtualization) + +(operating-system + (host-name "kimsufi") + + (bootloader (bootloader-configuration + (bootloader grub-bootloader) + (targets (list "/dev/sda" "/dev/sdb")) + (terminal-outputs '(console)))) + + ;; Add a kernel module for RAID-1 (aka. "mirror"). + (initrd-modules (cons* "raid1" %base-initrd-modules)) + + (mapped-devices + (list (mapped-device + (source (list "/dev/sda2" "/dev/sdb2")) + (target "/dev/md127") + (type raid-device-mapping)))) + + (swap-devices + (list (swap-space + (target "/dev/sda3")) + (swap-space + (target "/dev/sdb3")))) + + (issue + ;; Default contents for /etc/issue. + "\ +This is the GNU system at Kimsufi. Welcome.\n") + + (file-systems (cons* (file-system + (mount-point "/") + (device "/dev/md127") + (type "ext4") + (dependencies mapped-devices)) + %base-file-systems)) + + (users (cons (user-account + (name "guix") + (comment "guix") + (group "users") + (supplementary-groups '("wheel")) + (home-directory "/home/guix")) + %base-user-accounts)) + + (sudoers-file + (plain-file "sudoers" "\ +root ALL=(ALL) ALL +%wheel ALL=(ALL) ALL +guix ALL=(ALL) NOPASSWD:ALL\n")) + + ;; Globally-installed packages. + (packages (cons* tmux nss-certs gnutls wireguard-tools %base-packages)) + (services + (cons* + (service static-networking-service-type + (list (static-networking + (addresses (list (network-address + (device "enp3s0") + (value "@var{server-ip-address}/24")))) + (routes (list (network-route + (destination "default") + (gateway "@var{server-gateway}")))) + (name-servers '("213.186.33.99"))))) + + (service unattended-upgrade-service-type) + + (service openssh-service-type + (openssh-configuration + (openssh openssh-sans-x) + (permit-root-login #f) + (authorized-keys + `(("guix" ,(plain-file "@var{ssh-key-name.pub}" + "@var{ssh-public-key-content}")))))) + (modify-services %base-services + (sysctl-service-type + config => + (sysctl-configuration + (settings (append '(("net.ipv6.conf.all.autoconf" . "0") + ("net.ipv6.conf.all.accept_ra" . "0")) + %default-sysctl-settings)))))))) +@end lisp + +Don't forget to substitute the @var{server-ip-address}, +@var{server-gateway}, @var{ssh-key-name} and +@var{ssh-public-key-content} variables with your own values. + +The gateway is the last usable IP in your block so if you have a server +with an IP of @samp{37.187.79.10} then its gateway will be +@samp{37.187.79.254}. + +Transfer your operating system declaration @file{os.scm} file on the +server via the @command{scp} or @command{sftp} commands. + +Now all that is left is to install Guix with a @code{guix system init} +and restart. + +However we first need to set up a chroot, because the root partition of +the rescue system is mounted on an aufs partition and if you try to +install Guix it will fail at the GRUB install step complaining about the +canonical path of "aufs". + +Install packages that will be used in the chroot: + +@example +guix install bash-static parted util-linux-with-udev coreutils guix +@end example + +Then run the following to create directories needed for the chroot: + +@example +cd /mnt && \ +mkdir -p bin etc gnu/store root/.guix-profile/ root/.config/guix/current \ + var/guix proc sys dev +@end example + +Copy the host resolv.conf in the chroot: + +@example +cp /etc/resolv.conf etc/ +@end example + +Mount block devices, the store and its database and the current guix config: + +@example +mount --rbind /proc /mnt/proc +mount --rbind /sys /mnt/sys +mount --rbind /dev /mnt/dev +mount --rbind /var/guix/ var/guix/ +mount --rbind /gnu/store gnu/store/ +mount --rbind /root/.config/ root/.config/ +mount --rbind /root/.guix-profile/bin/ bin +mount --rbind /root/.guix-profile root/.guix-profile/ +@end example + +Chroot in /mnt and install the system: + +@example +chroot /mnt/ /bin/bash + +guix system init /root/os.scm /guix +@end example + +Finally, from the web user interface (UI), change @samp{netboot} to +@samp{boot to disk} and restart (also from the web UI). + +Wait a few minutes and try to ssh with @code{ssh +guix@@@var{server-ip-address>} -i @var{path-to-your-ssh-key}} + +You should have a Guix system up and running on Kimsufi; +congratulations! + @node Setting up a bind mount @section Setting up a bind mount diff --git a/doc/guix.texi b/doc/guix.texi index 89306c0b45..fd72761c92 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -53,7 +53,7 @@ Copyright @copyright{} 2017, 2019, 2020, 2021, 2022, 2023 Maxim Cournoyer@* Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@* Copyright @copyright{} 2017 George Clemmer@* Copyright @copyright{} 2017 Andy Wingo@* -Copyright @copyright{} 2017, 2018, 2019, 2020 Arun Isaac@* +Copyright @copyright{} 2017, 2018, 2019, 2020, 2023 Arun Isaac@* Copyright @copyright{} 2017 nee@* Copyright @copyright{} 2018 Rutger Helling@* Copyright @copyright{} 2018, 2021 Oleg Pykhalov@* @@ -2405,6 +2405,16 @@ BIOS or UEFI boot menu, where you can choose to boot from the USB stick. In order to boot from Libreboot, switch to the command mode by pressing the @kbd{c} key and type @command{search_grub usb}. +Sadly, on some machines, the installation medium cannot be properly +booted and you only see a black screen after booting even after you +waited for ten minutes. This may indicate that your machine cannot run +Guix System; perhaps you instead want to install Guix on a foreign +distro (@pxref{Binary Installation}). But don't give up just yet; a +possible workaround is pressing the @kbd{e} key in the GRUB boot menu +and appending @option{nomodeset} to the Linux bootline. +Sometimes the black screen issue can also be resolved by connecting a +different display. + @xref{Installing Guix in a VM}, if, instead, you would like to install Guix System in a virtual machine (VM). @@ -14168,6 +14178,16 @@ TeX package: guix import texlive fontspec @end example +Additional options include: + +@table @code +@item --recursive +@itemx -r +Traverse the dependency graph of the given upstream package recursively +and generate package expressions for all those packages that are not yet +in Guix. +@end table + @item json @cindex JSON, import Import package metadata from a local JSON file. Consider the following @@ -18060,10 +18080,6 @@ administrator's choice; reconfiguring does @emph{not} change their name. @item @code{home-directory} This is the name of the home directory for the account. -@item @code{home-directory-permissions} (default: @code{#o700}) -The permission bits for the home directory. By default, full access is -granted to the user account and all other access is denied. - @item @code{create-home-directory?} (default: @code{#t}) Indicates whether the home directory of this account should be created if it does not exist yet. @@ -31342,7 +31358,7 @@ The port on which to connect to the database. @cindex Mumi, Debbugs Web interface @cindex Debbugs, Mumi Web interface -@uref{https://git.elephly.net/gitweb.cgi?p=software/mumi.git, Mumi} is a +@uref{https://git.savannah.gnu.org/cgit/guix/mumi.git/, Mumi} is a Web interface to the Debbugs bug tracker, by default for @uref{https://bugs.gnu.org, the GNU instance}. Mumi is a Web server, but it also fetches and indexes mail retrieved from Debbugs. @@ -32675,7 +32691,7 @@ can run on headless servers. The Xvnc implementations provided by the @defvar xvnc-service-type -The @code{xvnc-server-type} service can be configured via the +The @code{xvnc-service-type} service can be configured via the @code{xvnc-configuration} record, documented below. A second virtual display could be made available on a remote machine via the following configuration: @@ -43941,6 +43957,62 @@ Extra content appended as-is to this @code{Host} block in @end deftp +@cindex Parcimonie, Home service +The @code{parcimonie} service runs a daemon that slowly refreshes a GnuPG +public key from a keyserver. It refreshes one key at a time; between every +key update parcimonie sleeps a random amount of time, long enough for the +previously used Tor circuit to expire. This process is meant to make it hard +for an attacker to correlate the multiple key update. + +As an example, here is how you would configure @code{parcimonie} to refresh the +keys in your GnuPG keyring, as well as those keyrings created by Guix, such as +when running @code{guix import}: + +@lisp +(service home-parcimonie-service-type + (home-parcimonie-configuration + (refresh-guix-keyrings? #t))) +@end lisp + +This assumes that the Tor anonymous routing daemon is already running on your +system. On Guix System, this can be achieved by setting up +@code{tor-service-type} (@pxref{Networking Services, @code{tor-service-type}}). + +The service reference is given below. + +@defvar parcimonie-service-type +This is the service type for @command{parcimonie} +(@uref{https://salsa.debian.org/intrigeri/parcimonie, Parcimonie's web site}). +Its value must be a @code{home-parcimonie-configuration}, as shown below. +@end defvar + +@c %start of fragment + +@deftp {Data Table} home-parcimonie-configuration +Available @code{home-parcimonie-configuration} fields are: + +@table @asis +@item @code{parcimonie} (default: @code{parcimonie}) (type: file-like) +The parcimonie package to use. + +@item @code{verbose?} (default: @code{#f}) (type: boolean) +Whether to have more verbose logging from the service. + +@item @code{gnupg-already-torified?} (default: @code{#f}) (type: boolean) +Whether GnuPG is already configured to pass all traffic through +@uref{https://torproject.org, Tor}. + +@item @code{refresh-guix-keyrings?} (default: @code{#f}) (type: boolean) +Guix creates a few keyrings in the @var{$XDG_CONFIG_DIR}, such as when running +@code{guix import} (@pxref{Invoking guix import}). Setting this to @code{#t} +will also refresh any keyrings which Guix has created. + +@item @code{extra-content} (default: @code{#f}) (type: raw-configuration-string) +Raw content to add to the parcimonie command. + +@end table + +@end deftp @c %end of fragment @@ -45869,47 +45941,48 @@ will not have the desired effect. @xref{Package Transformation Options, Guix provides packages for the @TeX{}, @LaTeX{}, ConTeXt, LuaTeX, and related typesetting systems, taken from the @uref{https://www.tug.org/texlive/, @TeX{} Live distribution}. However, -because @TeX{} Live is so huge and because finding your way in this maze -is tricky, we thought that you, dear user, would welcome guidance on how -to deploy the relevant packages so you can compile your @TeX{} and -@LaTeX{} documents. +because @TeX{} Live is so huge and because finding one's way in this +maze is tricky, so this section provides some guidance on how to deploy +the relevant packages to compile @TeX{} and @LaTeX{} documents. -@TeX{} Live currently comes in two flavors in Guix: +@TeX{} Live currently comes in two mutually exclusive flavors in Guix: @itemize @item The ``monolithic'' @code{texlive} package: it comes with @emph{every -single @TeX{} Live package} (more than 7,000 of them), but it is huge -(more than 4@tie{}GiB for a single package!). +single @TeX{} Live package} (roughly 4,200), but it is huge---more than +4@tie{}GiB for a single package! @item -The ``modular'' @samp{texlive-} packages: you start off with -a combination of @TeX{} Live @dfn{collections} and -@dfn{schemes}---``meta-packages'' such as -@code{texlive-collection-fontsrecommended}, or -@code{texlive-collection-context}, that provide the set of packages -needed in this particular domain, schemes being the name for collections -of such collections. This grants you core functionality and the main -commands---@command{pdflatex}, @command{dvips}, @command{luatex}, -@command{mf}, etc. You can then complete your selection with additional -collections or individual packages that provide just the features you -need---@code{texlive-listings} for the @code{listings} package, -@code{texlive-beamer} for Beamer, @code{texlive-pgf} for PGF/TikZ, and -so on. +A ``modular'' @TeX{} Live distribution, in which you only install the +packages, always prefixed with @samp{texlive-}, you need. @end itemize -We recommend using the modular package set because it is much less -resource-hungry. To build your documents, you would use commands such -as: +So to insist, these two flavors cannot be combined@footnote{No rule +without exception! As the monolithic @TeX{} Live does not contain the +@command{biber} executable, it is okay to combine it with +@code{texlive-biber}, which does.}. If in the modular setting your +document does not compile, the solution is not to add the monolithic +@code{texlive} package, but to add the set of missing packages from the +modular distribution. + +Building a coherent system that provides all the essential tools and, at +the same time, satisfies all of its internal dependencies can be +a difficult task. It is therefore recommended to start with sets of +packages, called @dfn{collections}, and @dfn{schemes}, the name for +collections of collections. The following command lists available +schemes and collections (@pxref{guix-search,, Invoking guix package}): @example -guix shell texlive-scheme-basic texlive-cm-super -- pdflatex doc.tex +guix search texlive-\(scheme\|collection\) | recsel -p name,description @end example -You can quickly end up with unreasonably long command lines though. The -solution is to instead write a manifest, for example like this one, -which would probably be a reasonable starting point for a French -@LaTeX{} user: +If needed, you may then complete your system with individual packages, +particularly when they belong to a large collection you're not otherwise +interested in. + +For instance, the following manifest is a reasonable, yet frugal +starting point for a French @LaTeX{} user: @lisp (specifications->manifest @@ -45918,31 +45991,18 @@ which would probably be a reasonable starting point for a French "texlive-scheme-basic" "texlive-collection-latexrecommended" "texlive-collection-fontsrecommended" - "texlive-babel-french" - ;; PGF/TikZ - "texlive-pgf" - - ;; Additional font. - "texlive-kpfonts")) + ;; From "latexextra" collection. + "texlive-tabularray" + ;; From "binextra" collection. + "texlive-texdoc")) @end lisp -You can then pass it to any command with the @option{-m} option: - -@example -guix shell -m manifest.scm -- pdflatex doc.tex -@end example - -@xref{Writing Manifests}, for more on manifests. In the future, we plan -to provide more collections and schemes. That will allow you to list -fewer packages. - -The main difficulty here is that using the modular package set forces -you to select precisely the packages that you need. You can use -@command{guix search}, but finding the right package can prove to be -tedious. When a package is missing, @command{pdflatex} and similar -commands fail with an obscure message along the lines of: +If you come across a document that does not compile in such a basic +setting, the main difficulty is finding the missing packages. In this +case, @command{pdflatex} and similar commands tend to fail with obscure +error messages along the lines of: @example doc.tex: File `tikz.sty' not found. @@ -45958,7 +46018,7 @@ kpathsea: Running mktexmf phvr7t @end example How do you determine what the missing package is? In the first case, -you'll find the answer by running: +you will find the answer by running: @example $ guix search texlive tikz @@ -45968,11 +46028,11 @@ version: 59745 @end example In the second case, @command{guix search} turns up nothing. Instead, -you can search the @TeX{} Live package database using the @command{tlmgr} -command: +you can search the @TeX{} Live package database using the +@command{tlmgr} command: @example -$ guix shell texlive-bin -- tlmgr info phvr7t +$ tlmgr info phvr7t tlmgr: cannot find package phvr7t, searching for other matches: Packages containing `phvr7t' in their title/description: @@ -45987,32 +46047,10 @@ tex4ht: texmf-dist/tex4ht/ht-fonts/alias/adobe/helvetic/phvr7t.htf @end example -The file is available in the @TeX{} Live @code{helvetic} package, which is -known in Guix as @code{texlive-helvetic}. Quite a ride, but we found -it! - -There is one important limitation though: Guix currently provides a -subset of the @TeX{} Live packages. If you stumble upon a missing -package, you can try and import it (@pxref{Invoking guix import}): - -@example -guix import texlive @var{package} -@end example - -Additional options include: - -@table @code -@item --recursive -@itemx -r -Traverse the dependency graph of the given upstream package recursively -and generate package expressions for all those packages that are not yet -in Guix. -@end table - -@quotation Note -@TeX{} Live packaging is still very much work in progress, but you can -help! @xref{Contributing}, for more information. -@end quotation +@noindent +The file is available in the @TeX{} Live @code{helvetic} package, which +is known in Guix as @code{texlive-helvetic}. Quite a ride, but you +found it! @node Security Updates @chapter Security Updates diff --git a/doc/local.mk b/doc/local.mk index 9d1e3ff7e4..97f0c3a92a 100644 --- a/doc/local.mk +++ b/doc/local.mk @@ -230,7 +230,7 @@ $(srcdir)/%D%/guix.1: scripts/guix.in $(sub_commands_mans) # source script (the first prerequisite) has been changed. The $(GOBJECTS) # prerequisite is solely meant to force these docs to be made only after all # Guile modules have been compiled. We also need the guix script to exist. -$(srcdir)/%D%/guix-%.1: scripts/guix guix/scripts/%.scm $(GOBJECTS) +$(srcdir)/%D%/guix-%.1: guix/scripts/%.scm $(GOBJECTS) scripts/guix -@case '$?' in \ *$<*) $(AM_V_P) && set -x || echo " HELP2MAN $@"; \ $(gen_man) --output="$@" "guix $*";; \ |